Appearance
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
| Status | Code | Detail |
|---|---|---|
| 400 | limit must be a positive integer | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 500 | authentication service unavailable | Internal 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)
| Field | Type | Required |
|---|---|---|
| name | string | Yes |
| team_id | object | No |
json
{
"name": "operator",
"team_id": "01J8Z3TEAM000000000000001"
}Responses
- 200 — Successful response
json
{
"id": "01J8Z3ROLE000000000000001",
"name": "operator",
"team_id": "01J8Z3TEAM000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 409 | the resource already exists | Conflict |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"id": "01J8Z3ROLE000000000000001",
"name": "operator",
"team_id": "01J8Z3TEAM000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| name | string | No |
| team_id | object | No |
json
{
"name": "senior-operator"
}Responses
- 200 — Successful response
json
{
"id": "01J8Z3ROLE000000000000001",
"name": "senior-operator",
"team_id": "01J8Z3TEAM000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Responses
- 200 — Successful response
json
{
"items": [
"orders:read:team",
"orders:write:team"
],
"next_cursor": "orders:write:team"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | limit must be a positive integer | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 404 | the requested resource was not found | Not Found |
| 500 | authentication service unavailable | Internal 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
| Parameter | Description |
|---|---|
| id | Path parameter. |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| permission_keys | array<string> | No |
| permissions | array<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
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required |
| 403 | step_up_required | Forbidden; Step-up Required |
| 404 | the requested resource was not found | Not Found |
| 422 | permission is not registered: orders:read:team | Invalid Permission; Invalid Request |
| 422 | permission must use resource:action:scope grammar | Invalid Permission; Invalid Request |
| 500 | authentication service unavailable | Internal Server Error |