API reference
Propose an immutable permission catalog
Current project owner proposes a versioned catalog. A separate current platform project approver must approve it. Idempotency-Key replays the exact actor and body.
POST/v1/projects/{project_id}/permission-catalogs
Authentication Bearer access token with audience taifa-management. Roles and local eligibility are reviewed separately from the OpenAPI bearer scheme.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
project_id | path | string | Yes | |
idempotency-key | header | string | Yes |
Request body
application/jsonRequiredCatalogProposal
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | Yes | Validation: min length 8; max length 500 |
permissions | Permission[] | Yes | Validation: min items 1; max items 32 |
Responses
201Successful Response
Content type: application/jsonCatalogRead
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
project_id | string | Yes | |
revision | integer | Yes | |
permissions | Permission[] | Yes | |
digest | string | Yes | |
status | pending_review | approved | superseded | revoked | Yes | |
proposer | string | Yes | |
approver | string | null | Yes | |
created_at | string | Yes | |
expires_at | string | Yes | |
actions | (approve | revoke)[] | Yes | |
revocations | RevocationRead[] | No |
Other responses
| Status | Description | Schema |
|---|---|---|
| 403 | Current project authority or independent review required | |
| 409 | Current exact proposal, catalog, version or idempotency conflict | |
| 413 | Exact JSON request exceeds 64 KiB | |
| 422 | Invalid exact reviewed policy or registration | |
| 503 | Configured owned issuer authority unavailable |
Request example
Illustrative only. TypeScript runs in Node.js on the server. Keep management tokens out of browser bundles. Replace the host, token, path values, and any header or required body placeholders before use. Examples do not send requests.
curl -X POST 'https://YOUR_IDENTITY_HOST/v1/projects/REPLACE_WITH_PROJECT_ID/permission-catalogs' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'idempotency-key: REPLACE_WITH_IDEMPOTENCY_KEY' \
-H 'Content-Type: application/json' \
--data '{
"permissions": [
{
"description": "Read assigned case records",
"id": "case.read"
}
],
"reason": "Define reviewed case access permissions"
}'Response example
No response example in the current specification.