Rolemaps

Rolemaps are join objects that relate users to Workspaces, folders, or files. A rolemap grants a user access to an object via a role. You can read, update, delete, and list rolemaps.

You create rolemaps via invitations.

Interacting with the rolemaps endpoint requires the id for a specific rolemap. You can find the appropriate rolemap id by first listing all rolemaps for a given object.

Read a Rolemap

GET 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.

200 Returns the rolemap object and a 200 if the call succeeds.

{
  "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": "[email protected]",
      "address": null,
      "profile_photo_url": "https://ws.example.com/assets/contact-ace461e8659e9aebf598e2c81fa125bb.png"
    }
  }
}

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.

Update a Rolemap

PUT 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.

200 Returns an empty message body and a 200 if the call succeeds.

//

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.

Delete a Rolemap

DELETE 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.

204 Returns an empty message body and a 204 if the call succeeds.

//

422 Returns a 422 with an error in the message body if you attempt to delete an Account rolemap.

Deleting a rolemap will revoke access to the rolemap's object.

Endpoint context is assumed for all delete actions. If you attempt to delete an Account rolemap from the /workspaces endpoint, the call will fail.

List all Rolemaps

GET 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.

200 Returns a paginated array of rolemap objects and a 200 if the call succeeds.

{
  "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": "[email protected]",
          "address": null,
          "profile_photo_url": "https://ws.example.com/assets/contact-ace461e8659e9aebf598e2c81fa125bb.png"
        }
      }
    }
  ]
}