Appearance
Permissions API Reference
GET /permissions/
List registered permissions
Use to populate policy editors and validate role changes; lists registered permission keys in ascending order. See REST pagination for the shared collection contract.
Required permission — iam:permissions:any
Responses
- 200 — Successful response
json
{
"items": [
{
"created_at": "2026-01-01T00:00:00Z",
"description": "Read orders in a team",
"key": "orders:read:team",
"registered_by": "orders-service"
}
],
"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 /permissions/
Register or update a permission
Use when an application service introduces a permission key. Keys must follow resource:action:scope grammar, with an optional ! deny prefix; registration is an upsert and increments the global permission registry version.
Required permission — iam:permissions:any
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| description | string | No |
| key | string | Yes |
| registered_by | string | Yes |
json
{
"description": "Read orders in a team",
"key": "orders:read:team",
"registered_by": "orders-service"
}Responses
- 200 — Successful response
json
{
"created_at": "2026-01-01T00:00:00Z",
"description": "Read orders in a team",
"key": "orders:read:team",
"registered_by": "orders-service"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden |
| 422 | permission must use resource:action:scope grammar | Invalid Permission |
| 500 | authentication service unavailable | Internal Server Error |
GET /permissions/{key}
Get a registered permission
Use to retrieve one registered permission by exact key. The key occupies one path segment; an optional ! deny prefix is part of the key. Unknown or syntactically invalid keys return the standard not-found response.
Required permission — iam:permissions:any Requires iam:permissions:any; reads do not require step-up authentication.
Path parameters
| Parameter | Description |
|---|---|
| key | Path parameter. |
Responses
- 200 — Successful response
json
{
"created_at": "2026-01-01T00:00:00Z",
"description": "Read orders in a team",
"key": "orders:read:team",
"registered_by": "orders-service"
}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 |