Tenant roles

The tenant role resource is used to group tenant permissions into a single role which can be assigned to users.

Tenant role object

{
  "id": "01988bb8-1e12-76cb-90be-28fbdb56174d",
  "tenant": "01988bb8-1cfb-7c87-9326-93op0349288e",
  "name": "Administrator",
  "description": "Full organizational access",
  "created_at": "2025-08-08 22:05:56",
  "updated_at": null
}

Fields

id
required readonly string
Unique ID of the record.
tenant
required readonly string
Unique ID of the tenant.
name
required string
Name of the role.
description
nullable string
Description of the role.
created_at
required readonly string
UTC timestamp of when the record was created.
updated_at
nullable readonly string
UTC timestamp of when the record was last updated.

Create a tenant role

POST /tenants/{tenantId}/roles

The request body must include a tenant role object.

Required permissions

tenant_roles:create

Response

HTTP status	Title	Description	Schema
201	Created	Successfully created	Tenant role object
400	Bad Request	Invalid or missing field(s)	Error object
404	Not Found	Tenant not found	Error object
409	Conflict	Role name already exists	Error object

List tenant roles

GET /tenants/{tenantId}/roles

Required permissions

If the user has the tenant_roles:read permission, they can view all roles for the tenant. Otherwise, they can only view roles that are assigned to them.

Response

HTTP status	Title	Description	Schema
200	OK		An associative array of tenant role objects
400	Bad Request	Invalid parameters in the request query	Error object
404	Not Found	Tenant not found	Error object

Read a tenant role

GET /tenants/{tenantId}/roles/{id}

Required permissions

If the user has the tenant_roles:read permission, they can view all roles for the tenant. Otherwise, they can only view roles that are assigned to them.

Response

HTTP status	Title	Description	Schema
200	OK		Tenant role object
400	Bad Request	Invalid parameters in the request query	Error object
404	Not Found	Tenant or role ID not found	Error object

List users with role

GET /tenants/{tenantId}/roles/{id}/users

Required permissions

If the user has the tenant_roles:read permission, they can view all users with the role. Otherwise, they can only view users in roles that are assigned to them.

Response

HTTP status	Title	Description	Schema
200	OK		An associative array of tenant user objects
400	Bad Request	Invalid parameters in the request query	Error object
404	Not Found	Tenant or role ID not found	Error object

Update a tenant role

PATCH /tenants/{tenantId}/roles/{id}

The request body must include parts of a tenant-role object.

Required permissions

tenant_roles:update

Response

HTTP status	Title	Description	Schema
200	OK	Updated tenant role record	Tenant role object
400	Bad Request	Invalid or missing field(s)	Error object
404	Not Found	Tenant or role ID not found	Error object
409	Conflict	Role name already exists	Error object

Delete a tenant role

DELETE /tenants/{tenantId}/roles/{id}

Required permissions

tenant_roles:delete

Response

HTTP status	Title	Description	Schema
204	No content	Successfully deleted
404	Not Found	Tenant ID not found	Error object

Was this page helpful?