# Rolemaps

Rolemaps are join objects that relate users to [Workspaces](/methods/workspaces.md), [folders](/methods/folders.md), or [files](/methods/files.md). A rolemap grants a user access to an object via a [role](/api/roles.md). You can **read**, **update**, **delete**, and **list** rolemaps.

{% hint style="info" %}
You create rolemaps via [invitations](/methods/invitations.md).
{% endhint %}

{% hint style="warning" %}
Interacting with the rolemaps endpoint requires the `id` for a specific rolemap. You can find the appropriate rolemap `id` by first [listing all rolemaps](/methods/rolemaps.md#list-all-rolemaps) for a given object.
{% endhint %}

## Read a Rolemap

<mark style="color:blue;">`GET`</mark> `https://ws-api.onehub.com/rolemaps/:id`

Retrieves the rolemap specified via `:id`.

#### Path Parameters

| Name | Type    | Description                                                      |
| ---- | ------- | ---------------------------------------------------------------- |
| :id  | integer | The unique identifier of the rolemap you would like to retrieve. |

{% tabs %}
{% tab title="200 Returns the rolemap object and a 200 if the call succeeds." %}

```yaml
{
  "rolemap": {
    "id": 20967,
    "state": "pending",
    "updated_at": "2016-05-03T13:46:48-07:00",
    "activated_at": null,
    "suspended_at": null,
    "deleted_at": null,
    "object_type": "Workspace",
    "role_name": "Creator",
    "available_roles": [
      "Administrator",
      "Moderator",
      "Collaborator",
      "Creator",
      "Downloader",
      "Printer",
      "Viewer",
      "Access Denied"
    ],
    "user_id": 6057,
    "user": {
      "id": 6057,
      "first_name": null,
      "last_name": null,
      "email": "user@example.com",
      "address": null,
      "profile_photo_url": "https://ws.example.com/assets/contact-ace461e8659e9aebf598e2c81fa125bb.png"
    }
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Rolemaps with an `object_type` of `Account`  were automatically granted to an account-level user and indicate access to all other object types within the account. Whereas, `Workspace`, `Folder`, and `File` rolemaps indicate access only to the object retrieved.
{% endhint %}

## Update a Rolemap

<mark style="color:orange;">`PUT`</mark> `https://ws-api.onehub.com/rolemaps/:id`

Updates the rolemap specified via `:id`.

#### Path Parameters

| Name | Type    | Description                                                    |
| ---- | ------- | -------------------------------------------------------------- |
| :id  | integer | The unique identifier of the rolemap you would like to update. |

#### Request Body

| Name       | Type   | Description                                                                                       |
| ---------- | ------ | ------------------------------------------------------------------------------------------------- |
| role\_name | string | The effective role granted to the user. This can only be updated to one of the `available_roles`. |

{% tabs %}
{% tab title="200 Returns an empty message body and a 200 if the call succeeds." %}

```yaml
//
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Endpoint context is assumed for all update actions. If you update an `Account` rolemap from the `/workspaces` endpoint, the API will automatically create a new `Workspace` rolemap on the specified Workspace, versus modifying that user’s account role.
{% endhint %}

## Delete a Rolemap

<mark style="color:red;">`DELETE`</mark> `https://ws-api.onehub.com/rolemaps/:id`

Deletes the rolemap specified via `:id`.

#### Path Parameters

| Name | Type    | Description                                                    |
| ---- | ------- | -------------------------------------------------------------- |
| :id  | integer | The unique identifier of the rolemap you would like to delete. |

{% tabs %}
{% tab title="204 Returns an empty message body and a 204 if the call succeeds." %}

```yaml
//
```

{% endtab %}

{% tab title="422 Returns a 422 with an error in the message body if you attempt to delete an Account rolemap." %}

```yaml
//
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Deleting a rolemap will revoke access to the rolemap's object.
{% endhint %}

{% hint style="warning" %}
Endpoint context is assumed for all delete actions. If you attempt to delete an `Account` rolemap from the `/workspaces` endpoint, the call will fail.
{% endhint %}

## List all Rolemaps

<mark style="color:blue;">`GET`</mark> `https://ws-api.onehub.com/:object/:id/rolemaps`

Lists all rolemaps for the `:object` (Workspace, folder, or file) specified via `:id`.

#### Path Parameters

| Name    | Type    | Description                                                                    |
| ------- | ------- | ------------------------------------------------------------------------------ |
| :object | string  | The type of object. Can be either `workspaces`, `folders`, or `files`.         |
| :id     | integer | The unique identifier of the object that you would like to list rolemaps from. |

{% tabs %}
{% tab title="200 Returns a paginated array of rolemap objects and a 200 if the call succeeds." %}

```yaml
{
  "current_page": 1,
  "total_entries": 12,
  "total_pages": 1,
  "offset": 0,
  "previous_offset": null,
  "next_offset": null,
  "per_page": 30,
  "items": [
    {
      "rolemap": {
        "id": 20967,
        "state": "pending",
        "updated_at": "2016-05-03T13:46:48-07:00",
        "activated_at": null,
        "suspended_at": null,
        "deleted_at": null,
        "object_type": "Workspace",
        "role_name": "Creator",
        "available_roles": [
          "Administrator",
          "Moderator",
          "Collaborator",
          "Creator",
          "Downloader",
          "Printer",
          "Viewer",
          "Access Denied"
        ],
        "user_id": 6057,
        "user": {
          "id": 6057,
          "first_name": null,
          "last_name": null,
          "email": "user@example.com",
          "address": null,
          "profile_photo_url": "https://ws.example.com/assets/contact-ace461e8659e9aebf598e2c81fa125bb.png"
        }
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.onehub.com/methods/rolemaps.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.