Identity & Access Management

Preview — pending review

This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.

Read the IAM vocabularies the console renders (permission resources + policy services)

GET
/scopes/{scopeId}/iam/catalog

Serves the IAM vocabulary the console used to hard-code: the permission-matrix resource keys the role editor renders a column per. It is static for the life of a deployment — derived from committed backend source of truth, not from tenant data — so a client may cache the response indefinitely and refetch only on reload. permissionResources is exactly iam/permission_matrix.json's resourceKeys, IN THAT ORDER, with a display label and grouping attached server-side; permissionLevels is that file's levels. The contract file has exactly one author (the Go auth service generates it and it is copied verbatim), so serving it here removes the client's undeclared copy rather than adding yet another one — a backend test fails if the served list and the contract file diverge. Validation: scopeId must resolve to a scope the caller can access (unknown or unauthorized → 404 NOT_FOUND, per the 404-not-403 rule). Async & state: Synchronous read; no state change. Errors: 401 when the session/credential is missing or expired; 404 when scopeId does not resolve or the caller has no IAM read on it; 500 on unexpected backend failure. Idempotency/Concurrency: Safe and cacheable; no idempotency key required. The response is identical for every caller in every scope of a given deployment.

Authorization

bearerToken
headerAuthorizationBearer <token>

An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Response Body

The permission-resource vocabulary for this deployment.

application/json
  1. response

The static IAM vocabulary the console renders - the role editor's permission-matrix columns. Constant for the life of a deployment; derived from committed backend source of truth, never from tenant data, so it is identical for every caller in every scope.

permissionMatrixVersion*integer

Version field of the permission-matrix contract the resource keys and levels come from.

permissionLevels*array<string>

The access levels a permission-matrix cell may hold, weakest first, exactly as the contract file lists them.

permissionResources*array<>

The permission-matrix resource keys, IN THE CONTRACT FILE'S OWN ORDER, each with its display label and group. Clients must render in array order and must not re-sort - the order is contract, not incidental.

curl -X GET "https://example.com/scopes/string/iam/catalog"
{  "permissionMatrixVersion": 1,  "permissionLevels": [    "none",    "read",    "manage"  ],  "permissionResources": [    {      "key": "compute",      "label": "Compute / Instances",      "group": "Infrastructure"    }  ]}