Skip to content
Docs

Roles

API Reference
Zones
Users

Roles

List user role assignments
GET/zones/{zoneId}/users/{userId}/roles
Assign role to user
POST/zones/{zoneId}/users/{userId}/roles
Revoke role from user
DELETE/zones/{zoneId}/users/{userId}/roles/{roleId}
ModelsExpand Collapse
RoleAssignment = object { id, created_at, principal_id, 8 more }

Represents a role assigned to a principal within a zone

id: string

Unique identifier of the role assignment

created_at: string

Entity creation timestamp

formatdate-time
principal_id: string

ID of the principal the role is assigned to (a user, application, or group ID).

principal_type: string

The kind of principal the role is assigned to: user, application, or group. A role assigned to a group is inherited by that group's members.

role_id: string

ID of the assigned role

role_identifier: string

Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.

minLength1
maxLength255
role_owner_type: "platform" or "customer"

Owner type of the assigned role. Disambiguates roles that share an identifier across owner types.

Accepts one of the following:
"platform"
"customer"
updated_at: string

Entity update timestamp

formatdate-time
zone_id: string

Zone this assignment belongs to

scope_id: optional string

The ID of the scoped resource. Null when the assignment is unscoped.

scope_type: optional string

The kind of resource this grant is scoped to (e.g. zone). Null when the assignment is unscoped (applies to the owning zone itself).

RoleAssignmentCreate = object { owner_type, role_id, role_identifier, 2 more }

Schema for assigning a role to a principal. Provide exactly one of role_id or role_identifier. When role_identifier is used, owner_type is required to disambiguate roles that share an identifier across owner types; owner_type must be omitted when role_id is used.

owner_type: optional "platform" or "customer"

Owner type of the role to assign. Required with role_identifier (an identifier is unique only per owner type); must be omitted with role_id.

Accepts one of the following:
"platform"
"customer"
role_id: optional string

ID of the role to assign. Provide exactly one of role_id or role_identifier; owner_type must be omitted when role_id is used.

role_identifier: optional string

Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.

minLength1
maxLength255
scope_id: optional string

The ID of the resource to scope the grant to. Provide together with scope_type, or omit both for an unscoped assignment. When scope_type is zone, this must reference a different zone in the same organization.

minLength1
scope_type: optional string

The kind of resource to scope the grant to (e.g. zone). Provide together with scope_id, or omit both for an unscoped assignment (applies to the owning zone itself). Only platform roles on the org zone may carry a scope.

minLength1