# 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.

```http
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](/docs/management-api). 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.

```http
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.