Skip to main content

Admin API guide

The admin API lives under /admin/api/. This page covers what every operation shares. The published operations, with their parameters and request bodies, are in the Postman collection and the OpenAPI document.

Authenticate​

Send an admin API key in the X-Admin-API-Key header.

curl "$BASE_URL/admin/api/policy-rules" \
  -H "X-Admin-API-Key: $ADMIN_KEY"

A missing, unknown or revoked key returns 401 with this body.

{"error":"unauthorized","error_description":"Valid admin API key required"}

The AuthZEN endpoint /access/v1/evaluation is not an admin path. It takes a Bearer token with the authzen scope, or the Basic credentials of a client entitled to authzen, and answers 401 to the admin key alone.

Manage keys​

The key set in PBAC_ADMIN_API_KEY is the first key. Minting and revoking keys is outside the published OpenAPI document. Mint and revoke further keys in the admin portal under Secrets, then Admin API Keys, or with the calls in Rotate keys and secrets. Use one key per person or system so that you can revoke one without touching the rest. A key that the dashboard manages is rotated from the environment's API-key card in the dashboard, not in the admin portal.

GET /admin/api/admin-keys lists every key, active and revoked, without the plaintext. The plaintext is not a one-time secret. Any holder of an admin key can read the stored plaintext of any key, and each read is audited. Treat every admin key as full admin access, and revoke a key you no longer trust.

Rotating or replacing the configured key, the credential key, the pepper and the OIDC signing keys are operator tasks that this API does not publish.

Page through a list​

Most lists return the whole array. Two are paged, the audit log (GET /admin/api/audit-logs) and the bundle revision history (GET /admin/api/bundle-audit, 50 rows a page by default). Pass page (zero-based) and size.

curl "$BASE_URL/admin/api/audit-logs?page=1&size=2" \
  -H "X-Admin-API-Key: $ADMIN_KEY"

The audit log answers with a page object. content holds the rows, and size, number and totalElements describe the page. Audit rows are always newest first. The bundle revision list answers with the array for that page and no page object.

Read an error​

StatusWhenBody
400A field fails validation, or an argument is not valid.error, and fieldErrors when fields failed
401The key is missing, unknown or revoked.error, error_description
404The id or name does not exist.empty
409The row already exists, or a connector is still in use.error, and connectorId and blockers for a connector. A duplicate managed resource gets an empty body
422The save was understood and then refused.see below

A policy save that OPA did not activate​

POST /admin/api/policy-rules, PUT /admin/api/policy-rules/{id}, PUT /admin/api/policy-rules/by-path and POST /admin/api/policy-bundle/deploy write the rules, ask OPA to load the new bundle, and wait for OPA to report it active. If OPA rejects the bundle, or cannot be reached, the AS restores the previous rows and returns 422.

{
  "error": "bundle_not_activated",
  "error_description": "OPA did not activate the deployed bundle ...",
  "expectedRevision": "…",
  "activeRevision": "…",
  "rolledBack": true
}

error is bundle_not_activated when OPA is up and refused the Rego, so the fault is in the policy. It is opa_unreachable when OPA could not be reached, so the fault is in the deployment. rolledBack is true, so your policy is what it was before the call.

Policy data that fails its schema​

A control declares a schema for its data row. A write to that row that breaks the schema returns 422 with dataKey and a failures array that names each failing path.