Skip to content

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 ​

StatusCodeDetail
400limit must be a positive integerInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
500authentication service unavailableInternal 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) ​

FieldTypeRequired
descriptionstringNo
keystringYes
registered_bystringYes
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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden
422permission must use resource:action:scope grammarInvalid Permission
500authentication service unavailableInternal 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 ​

ParameterDescription
keyPath 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 ​

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