Roles

Model

Fields

Field

Type

Description
object
"role"
id
string
name
string
team_id
string
scopes
The permissions the role grants: each resource mapped to its allowed actions (read, write, delete).

List Roles

Endpoint

Retrieve a list of roles for the current team.

roles:read
GET
/v1/roles

Query Parameters

Field

Type

Description
order_by
string Field used to order the roles. Defaults to "name". Accepted values: "name".
limit
number Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Defaults to "asc". Accepted values: "asc","desc".

Comments

  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: Role[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve Role

Endpoint

Retrieve a single role.

roles:read
GET
/v1/roles/:role_id

Path Parameters

Field

Type

Description
role_id
string Unique identifier of the role.

Response

200 
{
  message: string;
  data: Role;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Create Role

Endpoint

Create a new role for the current team.

roles:write
POST
/v1/roles

Request Body

Field

Type

Requirement

Description
id
string
Optional
Custom identifier for the role. One is generated when omitted.
name
string
Required
Display name for the role. Minimum length: 2. Maximum length: 60.
scopes
Optional
Scope names mapped to their permitted actions. Allowed scope keys: "users", "roles", "keys", "records", "projects", "metrics", "views", "billing", "pages", "monitors", "alerts", "chats", "secrets", "servers", "ingest_keys", "sources", "domains", "facets", "drains", "pulls", "checks", "logs". Allowed action values: "read", "write", "delete".

Comments

  • id cannot be role_owner, which is reserved.
  • Omit id and one is generated for you.
  • You can assign only scopes that your own authorization has.
  • The built-in role_owner role cannot be created, updated, or deleted.
  • Human roles must include projects:read.

Response

201 
{
  message: string;
  data: Role;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Update Role

Endpoint

Update an existing role.

roles:write
POST
/v1/roles/:role_id

Path Parameters

Field

Type

Description
role_id
string Unique identifier of the role.

Request Body

Field

Type

Requirement

Description
name
string
Optional
Display name for the role. Minimum length: 2. Maximum length: 60.
scopes
Optional
Scope names mapped to their permitted actions. Allowed scope keys: "users", "roles", "keys", "records", "projects", "metrics", "views", "billing", "pages", "monitors", "alerts", "chats", "secrets", "servers", "ingest_keys", "sources", "domains", "facets", "drains", "pulls", "checks", "logs". Allowed action values: "read", "write", "delete".

Comments

  • A role's id cannot be changed. Every user assignment points at it, so a rename would orphan them.
  • You can assign only scopes that your own authorization has.
  • The built-in role_owner role cannot be created, updated, or deleted.
  • Human roles must include projects:read.

Response

200 
{
  message: string;
  data: Role;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Delete Role

Endpoint

Delete a role from the current team.

roles:delete
DELETE
/v1/roles/:role_id

Path Parameters

Field

Type

Description
role_id
string Unique identifier of the role.

Comments

  • Roles with assigned users cannot be deleted. Reassign those users before deleting the role.
  • The built-in role_owner role cannot be created, updated, or deleted.

Response

200 
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Referenced Types

Scopes

Record<string, ("read" | "write" | "delete")[]>

Scope names mapped to their permitted actions. Allowed scope keys: "users", "roles", "keys", "records", "projects", "metrics", "views", "billing", "pages", "monitors", "alerts", "chats", "secrets", "servers", "ingest_keys", "sources", "domains", "facets", "drains", "pulls", "checks", "logs". Allowed action values: "read", "write", "delete".

Scope

users
roles
keys
records
projects
metrics
views
billing
pages
monitors
alerts
chats
secrets
servers
ingest_keys
sources
domains
facets
drains
pulls
checks
logs

ScopeValue

read
write
delete