API authentication

The Python management API accepts a bearer access token with the configured issuer and exact audience taifa-management. It verifies RS256 signature, key ID through JWKS, exp, iat, sub, iss, and aud. Routes then check current local eligibility and scoped roles. A successful OIDC login does not grant management access by itself.

Send a request

Use an approved private management URL and a short-lived access token issued for this API. Keep the token in backend memory or a protected server store. The portal BFF already uses backend-held tokens for personal routes. Do not put a management token in public JavaScript, a URL, or a command checked into source control.

GET /v1/me HTTP/1.1
Authorization: Bearer ACCESS_TOKEN_WITH_TAIFA_MANAGEMENT_AUDIENCE
Accept: application/json

GET /v1/me returns the current Person ID, issuer, subject, version, roles, memberships, and project access visible to that person. Its success response has a declared model in the generated management API reference. Some other operations still have unspecified success shapes in OpenAPI. The bearer security scheme does not encode every role or eligibility rule; endpoint-specific authorization is enforced separately by management.

Mutation authorization

Human mutations require a current authorized person, an actual strong login no more than 300 seconds old, a JSON reason of 8 to 500 characters, and a unique Idempotency-Key header of at most 200 characters. Platform administration requires phishing-resistant assurance. The server rechecks current sponsorship, Institution scope, and independent review at the transaction boundary. Replaying the same key and body returns the stored response; reusing a key for different input returns 409.

POST /v1/projects/PROJECT_ID/environments HTTP/1.1
Authorization: Bearer ACCESS_TOKEN_WITH_TAIFA_MANAGEMENT_AUDIENCE
Idempotency-Key: YOUR_UNIQUE_REQUEST_ID
Content-Type: application/json

The body depends on the operation; inspect its schema before sending. Do not substitute an ID token. Machine routes use their own reviewed service identity and request contract.

Interpret refusal

A missing or invalid bearer token yields an authentication failure, an unauthorized role or Institution yields 403, invalid input may yield 422, a stale or conflicting state often yields 409, and unavailable signing or audit dependencies yield 503. FastAPI responses generally contain a detail field, while validation failures contain structured detail entries. The response includes X-Request-ID for support correlation. Never record a full token or credential in diagnostics.