Skip to main content
GET
Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.
Lists the roles in your organisation. Use it to resolve the custom_role_ids on a member, or to find a role to pass to Update Member or Create Invite. There are two kinds:
  • Predefined roles have type: "predefined" and the fixed ids viewer, full_user and admin. Every organisation has them. An admin can turn one off, which sets active to false.
  • Custom roles have type: "custom" and a UUID id. Your admins build them from permission groups in Settings. They appear only on plans that include custom roles.
A role with active: false cannot be assigned. member_count counts the members who hold the role, suspended members included. Predefined roles have no description. Creating and editing custom roles is not part of this proposal. Do that in Settings.

​
Authentication

Requires an API key, or an OAuth token with directory:read. The caller must also be able to assign or manage roles: an organisation admin, or a role with either permission.

​
Query parameters

​
enum
Return only predefined or only custom roles.
​
string
The cursor from the previous page.
​
integer
default:"50"
Roles per page, up to 200.

​
Response

Returns 200 with a page of roles. Predefined roles come first, in the order viewer, full_user, admin, then custom roles by name.

​
Errors