Define roles that grant a set of permissions within a structure, and assign users to them.
A role is a named set of permissions that applies inside a structure. When a user holds a role on a structure, they can do what the role permits within that structure and every structure beneath it. Use roles to delegate user management without granting organization-wide access.
Use these endpoints to define your organization's roles from an external system, and keep a role's permission set aligned with your own access model.
Roles are defined here and assigned in the Structures section. Defining a role does not give anyone access. A user gains the role's permissions only once you assign them to the role on one or more structures.
There is no endpoint to list existing roles. Track a role's
idwhen you create it with Create a role. Managing a role defined outside the API, such as one created in the web app, is not currently supported.
Before you start
Key concepts
Role: A named set of permissions, scoped to one or more structure types. Each role has a name, a description, a permission list, and the structure types it applies to. Roles belong to the organization, not to a single structure.
Permission: One capability the role grants, such as PERMISSION_TYPE_VIEW_USERS. A role grants every permission in its list and nothing else. See the table below for the full set.
Structure type scope: The structure types a role can be assigned on, given in structure_type_ids. Sites and groups are structure types. A role scoped only to sites cannot be assigned on a group. Every role must be scoped to at least one type, and to no more than 100.
Default role: The role a new member receives when they are added to a structure of that type. is_default is read-only. Create and update requests cannot set it.
User count: The number of users who hold the role, across every structure. The Get a role endpoint omits this count unless you set include_user_count to true.
Permissions
| Permission | What the role grants |
|---|---|
PERMISSION_TYPE_CREATE_USERS | Create new users. |
PERMISSION_TYPE_MANAGE_USER_MEMBERSHIP | Add users to a structure the role applies to and remove them from it. |
PERMISSION_TYPE_EDIT_USERS | Edit user details and settings. |
PERMISSION_TYPE_VIEW_USERS | View user information. |
PERMISSION_TYPE_CHANGE_USER_STATUS | Activate and deactivate users. |
PERMISSION_TYPE_VIEW_DOCUMENTS | View the documents linked to the structure. |
PERMISSION_TYPE_LINK_DOCUMENTS | Link documents to the structure. |
PERMISSION_TYPE_MANAGE_DOCUMENTS | Manage the documents linked to the structure. |
Object relationships
| Object | Relates to |
|---|---|
| Role | The structure types it is scoped to, and the memberships that carry it |
| Structure type | The roles scoped to it, and the structures of that type |
| Membership | One user, one structure, and one role |
Ordering your calls
A typical workflow to assign a user to a role takes two calls, once you have the role's ID from Create a role.
- Call the Search structures endpoint to resolve the structures you don't already have IDs for.
- Call the Add users to a role endpoint with the role ID and the user-to-structure pairs.
Read the membership back with the List users by role endpoint. Check a role's current definition with Get a role before you assign it.
Updating a role is a full replacement. It clears any permission or structure type you do not send. Read the role first and send its complete permission set and type scope back.
Deleting a role is only available in the web app. A role that is still assigned to users continues to grant its permissions until you remove it.