Skip to content

Roles API Reference ​

GET /roles/ ​

List roles

Lists platform or team roles ordered by role ID. team_id optionally filters by team; omitted or null-scoped roles are platform roles. See REST pagination for the shared collection contract.

Required permission — iam:roles:any (or iam:roles:team scoped to the target team)

Responses ​

  • 200 — Successful response
json
{
  "items": [
    {
      "id": "01J8Z3ROLE000000000000001",
      "name": "operator",
      "team_id": "01J8Z3TEAM000000000000001"
    }
  ],
  "next_cursor": ""
}

Errors ​

StatusCodeDetail
400limit must be a positive integerInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
500authentication service unavailableInternal Server Error

POST /roles/ ​

Create a role

Use to define a platform-wide or team-scoped role. team_id may be a ULID or JSON null.

Required permission — iam:roles:any (or iam:roles:team scoped to the target team)

Request body (application/json) ​

FieldTypeRequired
namestringYes
team_idobjectNo
json
{
  "name": "operator",
  "team_id": "01J8Z3TEAM000000000000001"
}

Responses ​

  • 200 — Successful response
json
{
  "id": "01J8Z3ROLE000000000000001",
  "name": "operator",
  "team_id": "01J8Z3TEAM000000000000001"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
409the resource already existsConflict
500authentication service unavailableInternal Server Error

DELETE /roles/{id} ​

Delete a role

Use to remove a role and all user, group, and team-baseline bindings. Affected users' permission versions are invalidated.

Required permission — iam:roles:any (or iam:roles:team scoped to the target team)

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

GET /roles/{id} ​

Get a role

Use to retrieve one role and its scope before binding or changing permissions.

Required permission — iam:roles:any (or iam:roles:team scoped to the target team)

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "id": "01J8Z3ROLE000000000000001",
  "name": "operator",
  "team_id": "01J8Z3TEAM000000000000001"
}

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

PATCH /roles/{id} ​

Update a role

Use to rename a role or change its team scope. At least one field is required; team-scoped administrators cannot change team_id outside their scope. Role changes invalidate every affected user's permission version, including users inheriting the role through a team baseline.

Required permission — iam:roles:any (or iam:roles:team scoped to the target team)

Path parameters ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
namestringNo
team_idobjectNo
json
{
  "name": "senior-operator"
}

Responses ​

  • 200 — Successful response
json
{
  "id": "01J8Z3ROLE000000000000001",
  "name": "senior-operator",
  "team_id": "01J8Z3TEAM000000000000001"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

GET /roles/{id}/permissions ​

List permissions on a role

Lists the role's assigned permission keys in ascending order. Requires iam:roles:any or an applicable iam:roles:team grant for the role's team; reads do not require step-up authentication. See REST pagination for the shared cursor and response contract.

Required permission — iam:roles:any (or iam:roles:team scoped to the target team)

Path parameters ​

ParameterDescription
idPath parameter.

Responses ​

  • 200 — Successful response
json
{
  "items": [
    "orders:read:team",
    "orders:write:team"
  ],
  "next_cursor": "orders:write:team"
}

Errors ​

StatusCodeDetail
400limit must be a positive integerInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
404the requested resource was not foundNot Found
500authentication service unavailableInternal Server Error

PUT /roles/{id}/permissions ​

Set permissions on a role

Use to replace the complete permission set of a role. permission_keys is canonical; permissions is accepted as a legacy alias when permission_keys is absent. Every key must already be registered, including the optional ! deny prefix; applicable denies override matching allows across platform and team sources without role/source priority. A team-baseline deny therefore defeats a matching platform allow for an eligible member on that team's resource; users outside that team, including platform administrators without active membership, do not inherit the baseline deny and retain independent platform grants. Existing team baselines inherit the updated permissions, and affected users' permission versions are invalidated.

Required permission — iam:roles:any (or iam:roles:team scoped to the target team) Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.

Path parameters ​

ParameterDescription
idPath parameter.

Request body (application/json) ​

FieldTypeRequired
permission_keysarray<string>No
permissionsarray<string>No
json
{
  "permission_keys": [
    "orders:read:team",
    "orders:update:own"
  ]
}

Responses ​

  • 200 — Successful response
json
{
  "permissions": [
    "orders:read:team",
    "orders:update:own"
  ],
  "role_id": "01J8Z3ROLE000000000000001"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required
403step_up_requiredForbidden; Step-up Required
404the requested resource was not foundNot Found
422permission is not registered: orders:read:teamInvalid Permission; Invalid Request
422permission must use resource:action:scope grammarInvalid Permission; Invalid Request
500authentication service unavailableInternal Server Error