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.

get
Read a Rolemap

https://ws-api.onehub.com/rolemaps/:id
Retrieves the rolemap specified via :id.
Request
Response
Path Parameters
:id
required
integer
The unique identifier of the rolemap you would like to retrieve.
200: OK
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": "user@example.com",
"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.

put
Update a Rolemap

https://ws-api.onehub.com/rolemaps/:id
Updates the rolemap specified via :id.
Request
Response
Path Parameters
:id
required
integer
The unique identifier of the rolemap you would like to update.
Body Parameters
role_name
optional
string
The effective role granted to the user. This can only be updated to one of the available_roles.
200: OK
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
Delete a Rolemap

https://ws-api.onehub.com/rolemaps/:id
Deletes the rolemap specified via :id.
Request
Response
Path Parameters
:id
required
integer
The unique identifier of the rolemap you would like to delete.
204: No Content
Returns an empty message body and a 204 if the call succeeds.
//
422: Unprocessable Entity
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.

get
List all Rolemaps

https://ws-api.onehub.com/:object/:id/rolemaps
Lists all rolemaps for the :object (Workspace, folder, or file) specified via :id.
Request
Response
Path Parameters
:object
required
string
The type of object. Can be either workspaces, folders, or files.
:id
required
integer
The unique identifier of the object that you would like to list rolemaps from.
200: OK
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": "user@example.com",
"address": null,
"profile_photo_url": "https://ws.example.com/assets/contact-ace461e8659e9aebf598e2c81fa125bb.png"
}
}
}
]
}