Roles (legacy)

When an account is shared with other team members (as Operators), it is possible to define and assign custom roles in order to control their access rights. Each Operator can only have a single Operator role assigned to them at any one time. In addition, the account owner Operator can define roles for Application Users, assign these roles to applications, and set permissions on individual resources and operations.

Read Roles and Permissions in the Documentation section for more conceptual information on roles and permissions.

API Status General Availability: /roles /roles/:roleId /accounts/:accountId/accesses /accounts/:accountId/accesses/:accessId

Operator Roles

Jump To ↓

OperatorRoleDocument Data Model Create an Operator Role Read an Operator Role Update an Operator Role

OperatorRoleDocument Data Model

The OperatorRoleDocument contains the basic information about a role, as well as the allowed permissions if set.

A table of possible values for customFields.enabledStates is shown below:

Create an Operator Role

Roles are created with a POST request to the /roles resource containing a JSON document.

❗Notes

Only the account owner can create new roles.\n\nYou cannot create roles with the same name as the predefined admin and none roles.

Read an Operator Role

Read a single Operator role by ID.

Update an Operator Role

Update an Operator role with a PUT request to the /roles/:roleId resource containing a JSON document that is some subset of the OperatorRoleDocument. For example, just a new description field.

❗Note

Once a role has been created, its type cannot be updated.

Application User Roles

In addition to account-level Operator roles, Application Users can be assigned Application User roles that dictate which resources they can view and interact with.

New Application User roles automatically inherit some default immutable permissions. See the Role Permissions page for more information.

Jump To ↓

ApplicationUserRoleDocument Data Model Create an Application User Role Read an Application User Role Update an Application User Role Application Default Role

ApplicationUserRoleDocument Data Model

RoleScopesDocument Data Model

Create an Application User Role

❗Notes

Only the account owner can create new roles.\n\nYou cannot create roles with the same name as the predefined admin and none roles.

Read an Application User Role

Read a single Application User role by ID.

Update an Application User Role

Update a role with a PUT request to the /roles/:roleId resource containing a JSON document that is some subset of the RoleDocument. For example, just a new description field.

❗Note

Once a role has been created, its type cannot be updated.\n\nWhen updating customFields the entire object is replaced with the copy in the request payload.

Read all Roles

Get a list of all available roles for the account. The result may be paginated if there are more than 30 items.

Delete a Role

Remove a single role of either type by performing a DELETE request on the /roles/:roleId resource.

Update a Role's Project Scope

Use the special notation shown below to update a role with multiple new project scopes at once. For each ID, prefix with + to add or - to remove. Including neither will replace the list with the payload. It is not permitted to mix the two update methods at once.

The role itself can be viewed with the scopes using the withScopes=true query parameter:

Set a Role's Scoped Roles

Use a PUT request to update a role with a list of IDs of roles that can access that role. For example, a Repair Engineer Supervisor role can be added by ID to the roles scopes of the Repair Engineer role to enable the supervisor to see and assign it.

Read a Role's Scoped Roles

The roles that are visible to any given role are those that their current role is scoped to, i.e: those that include the current role in their scopes.roles field. The current user is determined using the Application User API Key authenticating the request.

Read an Account's Role

Read the current role of an account, as well as other authentication information. The response contains a list of AccessDocument objects, each of which has a role field.

Set an Account's Role

Set the role of an account with a roleId. This replaces the previously assigned role. The AccessDocument should contain the roleId of the role to be assigned.

Application Default Role

When an application is created, it will contain a default role that Application Users in that application will be automatically assigned. The default application default role is the pre-defined "base_app_user" role. This allows Application Users to view all resources in that application's project. Custom Application User roles can be created to specify a different subset of permissions as required. See Role Permissions for more information.

If the application's defaultRole changes at some point in the future, all Application Users within that application will be assigned the new role automatically.

Set an Application's Default Role