# Rolemaps

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

{% hint style="info" %}
You create rolemaps via [invitations](https://developer.onehub.com/methods/invitations).
{% 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](#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 %}