API reference

One contract. Every endpoint.

The published OpenAPI 3.1 contract documents 603 operations across 38 API groups. Custom APIs use /api/v1/realms/{realm}; protocol endpoints use /realms/{realm}.

Contract for the ProudAuth custom HTTP API (/api/v1/realms/{realm}/...) and the protocol endpoints served under the path-based issuer (/realms/{realm}). Generated from the server code (internal/httpapi) and kept in sync by tests/contract.

Conventions (docs/plan.md section 25):

• Errors. Custom APIs return RFC 9457 problem details (application/problem+json, schema Problem) with a stable code and the request_id. OAuth/OIDC endpoints return standard OAuth errors (OAuthError).
• Strict JSON. Request bodies must be application/json, are size-bounded, and are rejected when they contain duplicate or unknown members (additionalProperties: false).
• Authentication. Bearer tokens only in the Authorization header (never query strings). 401 for missing/invalid credentials, 403 for authenticated-but-disallowed, 404 where existence is concealed.
• Idempotency. Every authenticated POST accepts Idempotency-Key (24 hours, actor/realm/route-bound, matched on the exact path and body). Only successful responses are recorded, and responses that carried one-time secrets are never replayed.
• One-time secrets. Fields marked x-secret: true (client secrets, API keys, personal tokens, setup tokens, recovery codes, signing secrets, handoff codes, download tokens, continuation tokens) are returned exactly once.
• Concurrency. Editable resources return a weak ETag (W/"v{version}"); send it in If-Match. Stale versions return 412; where If-Match is required, omitting it returns 428.
• Pagination. Cursor-paginated lists accept cursor and limit and return next_cursor (empty string on the last page).
• Correlation. X-Request-Id is accepted (printable ASCII, at most 64 characters) or generated, and echoed on every response.
• Throttling. 429 and 503 responses include Retry-After.
• Trust classes and permissions. x-trust-class records the section 25.2 trust class of each operation; x-permissions lists the permissions the server checks (any one suffices unless noted). Organization-scoped org.* permissions are evaluated in the organization named by the path, whose existence is concealed (404) from callers without any permission in it.

Browse by area

Read public discovery

curl --fail https://identity.example.com/realms/main/.well-known/openid-configuration