Roles

List, read, create, update, enable, disable and delete the user roles on an Exsited instance.

Roles are the settings records for user roles, and each says whether it is a system role. You can list, read, create, update, enable or disable and delete roles. This area has 5 endpoints, and all seven SDKs call every one.

At a glance

Endpoint	Method	Path	What it does
List roles	GET	/settings/roles	Returns a page of roles under data, with paging details under pagination.
Create a role	POST	/settings/roles	Creates a role and returns it under role.
Retrieve a role	GET	/settings/roles/{role_id}	Returns one role by its id, under role.
Delete a role	DELETE	/settings/roles/{role_id}	Deletes a role. A system role is refused.
Update a role	PATCH	/settings/roles/{role_id}	Changes a role, or enables or disables it.

Before you call

Register your API credentials once when your app starts, as shown in Authentication. Every SDK sample on these pages then gets its client in one line. With cURL, send the access token in an Authorization header: Authorization: Bearer $ACCESS_TOKEN.

Things to know

• Responses wrap a role in role. A single read returns {"role": {...}}.
• is_system_role marks the built-in roles. A delete of a system role is refused.
• Listings page by cursor. Records sit under data; pass pagination.next_cursor as cursor to read the next page, and stop when pagination.has_more is false.