API Reference

Complete reference for the Headless Auth Platform HTTP API. It contains everything an external project needs to call the service — addressing, authentication, every endpoint, and the error model — without reading the source. For a guided tutorial see the Integration guide; for a first run see Getting Started.

• API style: REST over HTTPS, JSON request/response (OAuth token/SCIM use form/JSON as noted). OpenAPI: 3.1.0. Version: 0.1.0.
• Machine-readable spec / SDK generation: target/openapi/openapi.json (108 paths, 130 operations) — import into Postman/Insomnia or generate typed clients.
• Accuracy: every operation below exists in the running service today. Planned features (LDAP login, device-code grant, SAML SP-initiated AuthnRequest/SLO) are not included.
• Secrets: all examples use placeholders like <TENANT_ID>, <CLIENT_ID>, <ACCESS_TOKEN> — never put real secrets in shared commands. Examples assume a base URL of http://localhost:8000.

1. Overview: base URL & addressing model

The API has two address spaces:

• Each tenant is an isolated environment with its own users, signing keys, and policies. A tenant's issuer is {HAP_ISSUER_BASE_URL}/t/{tenant_slug} (e.g. http://localhost:8000/t/acme).
• Global /v1/* endpoints identify the tenant via a header (X-Tenant-Id) or, for OAuth endpoints, via the tenant slug in the path.
• The platform ships with no tenants; create one with POST /v1/tenants (see §6.9).

Content types: JSON (application/json) for most endpoints; the OAuth token, introspect, revoke, authorize (POST), and SAML ACS endpoints accept form-encoded bodies (application/x-www-form-urlencoded), per the relevant standards.

In-cluster consumers: split the network path from the issuer identity

If your app calls this service from inside the same Kubernetes/EKS cluster, do not use the public ingress URL (e.g. https://auth.wbsp-demo.com) for the HTTP calls. Pods generally cannot reach their own cluster's public load balancer (LB hair-pinning is not supported on EKS by default) — requests to the public URL time out.

Use a split-horizon configuration:

• Network path → the in-cluster Service. Make every HTTP call (discovery, JWKS, OTP, authorize, token, userinfo, admin) to the cluster-internal Service address. The platform injects it when you declare a uses: dependency on this app (feature 034): the exposed auth port surfaces as HEADLESS_AUTH_AUTH_HOST / HEADLESS_AUTH_AUTH_PORT (i.e. test-headless-auth.<namespace>.svc.cluster.local:8080).
• Identity → the public issuer. Keep validating ID/access tokens against the public issuer ({HAP_ISSUER_BASE_URL}/t/{tenant_slug}, e.g. https://auth.wbsp-demo.com/t/wbsp) for iss/aud. Tokens are signed with the issuer baked in, so the trusted identity is always the public URL regardless of which network path fetched them. If your OIDC library derives endpoints from the discovery document (which advertises public URLs), override the endpoint host with the in-cluster Service for the actual calls while leaving iss/aud checks pointed at the public issuer.

Apps reached from outside the cluster (browsers, server-to-server over the internet) use the public URL for everything as normal.

2. Authentication

There are five ways a request proves who it is. Each endpoint below states which it needs.

Public clients (SPA/native) use PKCE only (no client secret). Outbound webhook deliveries are HMAC-signed with X-HAP-Signature (see §6.12) — that is for your receiver to verify, not an inbound scheme.

Auth quick reference by group:

3. Errors

OAuth/OIDC endpoints return the RFC 6749 §5.2 JSON shape; other endpoints return a similar body. The HTTP status conveys the category.

{ "error": "invalid_request", "error_description": "human-readable detail" }

Interaction signals on /oauth2/authorize (login_required, consent_required, interaction_required) are normal flow, returned as 401 JSON for your client to act on (log the user in, show consent, or run step-up), not hard errors.

4. Health

GET /healthz

Liveness. Auth: none. 200 → {"status":"ok"}.

GET /readyz

Readiness (checks database + cache). Auth: none. 200 → {"status":"ok","checks":{"database":"ok","redis":"ok"}}; 503 if a dependency is down.

curl -s http://localhost:8000/readyz

5. Discovery & OAuth 2.0 / OpenID Connect (per tenant)

All paths are under /t/{tenant_slug}/.

GET /t/{tenant_slug}/.well-known/openid-configuration

GET /t/{tenant_slug}/.well-known/oauth-authorization-server

OIDC Discovery / OAuth AS metadata. Auth: none. 200 → JSON with issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, introspection_endpoint, revocation_endpoint, grant_types_supported (authorization_code, refresh_token, client_credentials), code_challenge_methods_supported (["S256"]), and id_token_signing_alg_values_supported.

curl -s http://localhost:8000/t/acme/.well-known/openid-configuration

GET /t/{tenant_slug}/oauth2/jwks

Public signing keys (JWKS) for verifying issued tokens. Auth: none. 200 → {"keys":[{"kty","use":"sig","alg","kid",…}]}.

GET|POST /t/{tenant_slug}/oauth2/authorize

Authorization-code request with PKCE. Auth: login_token (the authenticated user). Query (GET) or form (POST) params: response_type=code (required), client_id, redirect_uri (exact match), scope (e.g. openid profile email), state, code_challenge, code_challenge_method=S256, nonce (optional), login_token, consent (granted), acr_values (optional, e.g. aal2). Success: 302 redirect to redirect_uri?code=<code>&state=<state>. Signals: 401 login_required (authenticate first), consent_required (+ scopes), interaction_required (+ required_acr — run step-up).

curl -si "http://localhost:8000/t/acme/oauth2/authorize?response_type=code\
&client_id=<CLIENT_ID>&redirect_uri=https://app.example/callback\
&scope=openid%20profile%20email&code_challenge=<CHALLENGE>&code_challenge_method=S256\
&login_token=<LOGIN_TOKEN>&consent=granted" | grep -i location

POST /t/{tenant_slug}/oauth2/token

Exchange a code / refresh token / client credentials for tokens. Auth: OAuth client auth (confidential clients send client_secret or HTTP Basic; public clients use PKCE). Body (form):

• grant_type=authorization_code: code, redirect_uri, code_verifier, client_id.
• grant_type=refresh_token: refresh_token, client_id.
• grant_type=client_credentials: client_id, client_secret.

200 →

{ "access_token":"<jwt>", "token_type":"Bearer", "expires_in":3600,
  "scope":"openid profile email", "id_token":"<jwt>", "refresh_token":"<opaque>" }

(id_token only when openid scope was granted; refresh_token when enabled.) Reusing a rotated refresh token revokes the whole token family.

curl -s -X POST http://localhost:8000/t/acme/oauth2/token \
  -d grant_type=authorization_code -d code=<CODE> \
  -d redirect_uri=https://app.example/callback -d code_verifier=<VERIFIER> -d client_id=<CLIENT_ID>

GET /t/{tenant_slug}/oauth2/userinfo

Claims for the access token's user. Auth: end-user bearer (header only; query-string tokens are rejected). 200 → {"sub","email","email_verified","name",…} (claims per granted scopes).

curl -s http://localhost:8000/t/acme/oauth2/userinfo -H "Authorization: Bearer <ACCESS_TOKEN>"

POST /t/{tenant_slug}/oauth2/introspect

Token introspection (RFC 7662). Auth: OAuth client auth. Body (form): token, client_id (+ secret). 200 → {"active":true,"scope","client_id","sub","exp","token_type"} or {"active":false}.

POST /t/{tenant_slug}/oauth2/revoke

Revoke an access or refresh token (RFC 7009). Auth: OAuth client auth. Body (form): token, client_id (+ secret). 200 → {"status":"ok"} (revoking a refresh token revokes its session/family; an access token's jti is denied until expiry).

6. Endpoint catalogue (global /v1 and /scim/v2)

6.1 Auth flows — X-Tenant-Id

Passwordless primary login (no password; returns the same login_token). Request steps are uniform 202 (no enumeration); verify failures are 401. Subject to per-tenant rate limiting and, at the subsequent /authorize, the application access gate (§6.9).

Codes/links are single-use, short-lived, attempt-limited. Sessions record the method (email_otp / sms_otp / magic_link) at assurance level 1. A per-tenant passwordless_jit_provisioning flag (default off) controls whether a first passwordless contact with an unknown identifier creates the identity. (TOTP/authenticator stays a second factor; passkeys under §6.5 already cover passwordless-primary.)

IdentityResponse = {id, email, email_verified, name, given_name, family_name, status, mfa_enabled, custom_claims, created_at} — never includes credential material.

curl -s -X POST http://localhost:8000/v1/auth/login -H "X-Tenant-Id: <TENANT_ID>" \
  -H "Content-Type: application/json" -d '{"email":"user@acme.example","password":"<PW>"}'

6.2 Identities (admin) — X-Admin-Key + X-Tenant-Id (scope identities:*)

6.3 Sessions

SessionResponse = {id, auth_method, aal, mfa_completed, ip_address, user_agent, geo_country, geo_city, status, last_activity_at, created_at}.

6.4 MFA — X-Tenant-Id, with login_token in body

6.5 Passkeys / WebAuthn — X-Tenant-Id

credential is the standard WebAuthn JSON from the browser ceremony.

6.6 Federation: social/OIDC & SAML — X-Tenant-Id

6.7 RBAC — admin (X-Admin-Key + X-Tenant-Id)

Effective permissions are embedded in the access token's permissions claim.

6.8 Admin / provisioning

application_type: web, spa, native, machine_to_machine, saml_sp. Use spa/native for public (PKCE) clients; web/machine_to_machine for confidential clients.

Application lifecycle (scope applications:write) — self-service remediation of a tenant's own applications (e.g. a leaked client secret), no platform-operator ticket needed. Also available to a tenant admin in the Hosted Admin console (/t/{slug}/hosted/admin/applications), with identical effects. Disabling, deleting, or immediate-rotating runs an app-scoped revocation cascade — the client's access tokens, refresh-token sessions, and per-app access grants stop working within seconds — while leaving the user's tenant-wide SSO session intact. See the application-lifecycle guide.

Unknown / other-tenant / deleted ids return a non-enumerating 404 application_not_found.

Application administrators (feature 018) — delegated, app-scoped control. A tenant admin can designate a user as an administrator of a single application. An application admin gets full control of that one application — the lifecycle actions above, the access entitlements in §6.9, and co-administrator management — without any tenant-wide authority (they cannot create applications, manage other applications, change tenant settings, or grant tenant administration). The application lifecycle and per-user access endpoints therefore accept either an admin key carrying applications:write (the control plane, unchanged) or a session token of a tenant admin / administrator of that application; the latter is how an application admin acts headlessly.

A tenant admin (or app admin) can also create and fully manage an application — including creating one (POST /v1/applications) — and manage all of the above from the Hosted Admin console (/t/{slug}/hosted/admin/applications). Being an application admin is administrative authority, not end-user access: an app admin who also needs to use a restricted app still needs a normal access grant.

Application access control (access_mode): open (default — any authenticated identity may obtain tokens, unchanged behaviour) or restricted (issuance is gated; see §6.9). When an access_decision_endpoint is set, the platform calls that HTTPS endpoint at authorize/refresh time and the returned decision governs (the signing secret is returned once as access_decision_secret, and the request is HMAC-signed exactly like webhooks). Fail-closed by default (access_decision_fail_open=false).

6.9 Application access entitlements — admin (application_access:*)

For a restricted application, the external control plane grants/revokes which identities may use it. Stored entitlements are the fallback when no decision endpoint is configured (the endpoint "wins" when present).

A non-entitled but fully authenticated identity is refused at …/oauth2/authorize and …/oauth2/token with the distinct access_denied / application_access_denied outcome (see §3) — never confused with an authentication failure. Revoking access blocks future refresh and the next authorize; already-issued short-lived access tokens expire naturally (revoke sessions to cut access immediately).

The same per-user grants are also manageable by a logged-in tenant admin in the Hosted Admin console at /t/{slug}/hosted/admin/users/{identity_id}/access (feature 017), with identical effect (audited as the acting admin). The console surfaces each application's access_mode because a direct grant only changes access for restricted applications — it is inert for open apps and for apps governed by an external decision endpoint.

Scoped admin keys — admin (admin_keys:write)

Least-privilege keys (e.g. one limited to application_access:write for the control plane). Presented in the same X-Admin-Key header.

curl -s -X POST http://localhost:8000/v1/tenants -H "X-Admin-Key: <ADMIN_KEY>" \
  -H "Content-Type: application/json" -d '{"name":"Acme","slug":"acme","password_policy":{"min_length":8}}'

6.10 SCIM 2.0 — SCIM bearer + X-Tenant-Id

Authenticate with the provider's SCIM bearer token (returned when creating a SCIM-enabled provider) plus X-Tenant-Id.

6.11 AI suggestions — admin (X-Admin-Key + X-Tenant-Id)

6.12 Webhooks — admin (X-Admin-Key + X-Tenant-Id)

Verifying deliveries: each POST to your endpoint carries X-HAP-Signature: t=<ts>,v1=<hmac_sha256(secret, "<ts>.<body>")> and X-HAP-Event: <event_type>. Recompute the HMAC with your signing_secret and compare.

Event types: identity.created, identity.updated, identity.email_changed, identity.suspended, identity.reinstated, identity.deleted, session.created, session.revoked, mfa.enrolled, credential.compromised, login.blocked, invitation.accepted, invitation.rejected. Identity-lifecycle deliveries carry {event, data:{event_id, occurred_at, identity_id, email, [reason]}} — de-duplicate on event_id (delivery is at-least-once) and join on identity_id. identity.email_changed carries the new email only. Invitation deliveries carry {event, data:{event_id, occurred_at, invitation_id, application_id, identity_id, email, outcome, [reason]}}.

6.13 Invitations — application-authenticated (own client credentials)

Invite a person by email to join the platform and gain access to the inviting application. The app calls the create endpoint with its own OAuth2 client credentials (HTTP Basic client_id:client_secret); the tenant and inviting application are derived from the credential. The return URL is configured on the application (invitation_return_url, set via PATCH /v1/applications/{id}), not passed per request — an app without one cannot invite (409).

• already_registered is true only when an active identity already exists; otherwise a pending identity is created (or an existing pending one reused). Validity window defaults to 5 days (HAP_INVITATION_TTL_SECONDS).
• send_email=true requires both email_text_body and email_html_body; the platform substitutes {{invitation_url}} and {{email}} and reports email_delivery as sent/failed (best-effort). Otherwise email_delivery is not_sent and the app emails the invitation_url itself.
• Accepting activates a pending identity (pending → active, email marked verified), signs the invitee in (an hap_session cookie; auth_method=invitation, aal=1), and — for a restricted application — grants access. Required MFA is not bypassed; step-up still applies downstream.
• Result token: every redirect to the return URL carries ?invitation_result=<JWT>. Verify it server-side with the tenant JWKS (/t/{slug}/oauth2/jwks); aud=urn:hap:invitation-result, claims {invitation_id, application_id, outcome: accepted|rejected, [reason: declined|expired|invalid|ineligible], [identity_id]}.
• Creation is rate-limited per (tenant, application), stricter on the platform-sends-email path.

6.14 Personal / CLI access tokens — admin (X-Admin-Key + X-Tenant-Id)

Long-lived, opaque, identity-bound bearer tokens for non-browser clients (e.g. a git CLI presenting username:token over HTTP Basic). A relying application mints one on a signed-in identity's behalf with a narrow scope and a gateway validates a presented token via introspection. Tokens are opaque (hap_pat_…), hashed at rest, and the secret is shown once.

• Issuance requires the identity to be active (else 409); expires_in_days is clamped to the platform maximum (HAP_PAT_MAX_TTL_SECONDS, default 365 d). The two scopes can be held by a least-privilege admin key, so the minting/validation path holds no broad admin rights.
• Introspection is a live check: it returns active:false (and no identity) for any token that is unknown, malformed, expired, revoked, or whose identity is not active — so suspending or deleting an identity makes its personal tokens stop validating within seconds. identity_id equals the OIDC sub. last_used_at is updated on an active result.
• Revocation cascade: revoking a token, or suspending/deleting its identity, invalidates it. Personal tokens always cascade. A per-tenant flag revoke_tokens_on_identity_suspend (set via PATCH /v1/tenants/{id}, default off) extends the same suspend/delete cascade to the identity's interactive sessions and OAuth access/refresh tokens.

6.15 Groups & tenant administration — mixed principals

User-owned groups (organisations/collectives/clubs) plus the tenant-administrator attribute that backs the Hosted Admin Console. Two principals are used: identity self-service (Authorization: Bearer <session token> + X-Tenant-Id) for running your own group, and tenant-admin oversight (X-Admin-Key + X-Tenant-Id) for tenant-wide actions.

Self-service — Authorization: Bearer <session token> + X-Tenant-Id

Tenant-admin oversight — X-Admin-Key + X-Tenant-Id

• Group creation policy is per-tenant via PATCH /v1/tenants/{id} with group_creation_policy = {mode: "disabled" | "any_active_user" | "capability"} (default disabled). In capability mode, an identity also needs a group-create-grant.
• Invariants (all refusals carry a machine error_code): exactly one owner per group; the owner is always an admin; at least one admin always remains; the last login-capable tenant admin (last_tenant_admin) and the sole owner of any group (sole_group_owner) can never be disabled/deleted until resolved. Codes: last_tenant_admin, sole_group_owner, group_must_have_owner, group_must_have_admin, owner_is_always_admin, transfer_target_not_admin, admin_member_owner_only, group_creation_forbidden (403 for authorization-style codes, 409 for state/lockout).
• Group → application access is additive: a member of a group that grants an application is allowed, unioned with any direct per-identity grant (an active member only — a disabled member gets no group-derived access). A group's application grants are managed by its owner/admins and, for oversight, by any tenant admin (via the session-token endpoints above or the Hosted group page) without needing group membership (feature 017).
• Hosted UI (opt-in, tenants with hosted_login_enabled): /t/{slug}/hosted/admin (tenant Admin Console), /t/{slug}/hosted/groups and /t/{slug}/hosted/groups/{id} (group self-service) — a thin client over exactly these endpoints.

6.16 SSH keys for git access — mixed principals

Identity-bound SSH public keys the platform owns, plus a lookup that resolves a presented key (or its fingerprint) to its owning identity — the SSH counterpart to personal access tokens (6.14): a git gateway resolves an SSH key the same way it introspects a PAT. Public keys are not secrets, so the key is stored in clear and a SHA256:… fingerprint is the lookup key. The platform holds no repository knowledge — per-repo authorization stays in the gateway. Accepted key types: Ed25519 and RSA ≥ 2048; ECDSA, DSA, and shorter RSA are rejected.

Admin — X-Admin-Key + X-Tenant-Id

Self-service — Authorization: Bearer <session token> + X-Tenant-Id (acts on your own identity)

• Validation (registration): unsupported/weak or malformed keys are refused with a machine error_code — ssh_key_invalid (unparseable) or ssh_key_unsupported_type (ECDSA/DSA/short RSA), both 422. A key whose fingerprint is already active in the tenant is refused 409 ssh_key_already_registered; the same key may exist under a different tenant, and a removed key may be registered again.
• Lookup is a live check: it returns active:false (and no identity) for any key that is unknown, removed, expired, or whose identity is not active — so suspending or deleting an identity makes its SSH keys stop resolving within seconds, with no separate revocation step. identity_id equals the OIDC sub; last_used_at is updated on an active result. Provide a fingerprint (SHA256:…) or a full public_key. A gateway that caches results should use a TTL under 5 s so caching never defeats the revocation budget.
• Expiry is optional and defaults to none (HAP_SSH_KEY_MAX_TTL_SECONDS, default 0 = unlimited; the RSA floor is HAP_SSH_RSA_MIN_BITS, default 2048). scope/audience are opaque — stored and echoed, never interpreted.

6.17 UI appearance & branding — mixed principals

Per-tenant appearance applied consistently across every platform-rendered screen (Hosted Login and signed-out pages, the invitation welcome page, and the Admin Console). One config — palette (accent_color, background_color, text_color, error_color), font_family, logo_url, favicon_url, product_name — settable by both a platform operator (admin API) and a tenant admin (self-service Hosted page). See the appearance customization guide for the full field reference and worked examples.

Admin — X-Admin-Key + X-Tenant-Id

Self-service (tenant admin) — Hosted UI

• Validation (single source of truth, domain/branding.py): font_family is a family name validated against an allowlisted web-font provider (the platform builds the Google-Fonts link — arbitrary font URLs are rejected); logo_url/favicon_url must be absolute HTTPS (no data:, relative, or non-HTTPS). Unsafe or unknown input is refused 422 invalid_request.
• Low colour contrast warns but does not block (WCAG AA 4.5:1): such cases return branding_warnings on the admin response (and inline on the Hosted page) without failing the save.
• Backward compatible: unbranded tenants and legacy accent_color/logo_url-only tenants render unchanged. Self-service saves emit a branding.updated audit row (the admin-API path rides tenant.updated).

7. Worked example — login to token (end to end)

BASE=http://localhost:8000

# (admin) create a tenant and a public application
TENANT=$(curl -s -X POST $BASE/v1/tenants -H "X-Admin-Key: <ADMIN_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme","slug":"acme","password_policy":{"min_length":8}}')
TENANT_ID=$(echo "$TENANT" | python -c "import sys,json;print(json.load(sys.stdin)['id'])")

APP=$(curl -s -X POST $BASE/v1/applications -H "X-Admin-Key: <ADMIN_KEY>" \
  -H "X-Tenant-Id: $TENANT_ID" -H "Content-Type: application/json" \
  -d '{"name":"Acme Web","application_type":"spa","redirect_uris":["https://app.example/cb"]}')
CLIENT_ID=$(echo "$APP" | python -c "import sys,json;print(json.load(sys.stdin)['client_id'])")

# (end user) register + login
curl -s -X POST $BASE/v1/auth/register -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" -d '{"email":"u@acme.example","password":"a strong passphrase"}'
LT=$(curl -s -X POST $BASE/v1/auth/login -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" -d '{"email":"u@acme.example","password":"a strong passphrase"}' \
  | python -c "import sys,json;print(json.load(sys.stdin)['login_token'])")

# PKCE
read V C < <(python -c "import os,base64,hashlib;v=base64.urlsafe_b64encode(os.urandom(32)).rstrip(b'=').decode();print(v, base64.urlsafe_b64encode(hashlib.sha256(v.encode()).digest()).rstrip(b'=').decode())")

# authorize -> code
CODE=$(curl -si "$BASE/t/acme/oauth2/authorize?response_type=code&client_id=$CLIENT_ID\
&redirect_uri=https://app.example/cb&scope=openid%20profile%20email&code_challenge=$C\
&code_challenge_method=S256&login_token=$LT&consent=granted" | grep -i location | sed -E 's/.*code=([^&]+).*/\1/')

# token -> tokens, then userinfo
TOKENS=$(curl -s -X POST $BASE/t/acme/oauth2/token -d grant_type=authorization_code \
  -d code=$CODE -d redirect_uri=https://app.example/cb -d code_verifier=$V -d client_id=$CLIENT_ID)
AT=$(echo "$TOKENS" | python -c "import sys,json;print(json.load(sys.stdin)['access_token'])")
curl -s $BASE/t/acme/oauth2/userinfo -H "Authorization: Bearer $AT"

8. Generating clients & next steps

• Generate a typed SDK from the OpenAPI document — available here in both formats: openapi.yaml (this folder) and target/openapi/openapi.json (OpenAPI 3.1). Feed either to openapi-generator, Postman/Insomnia, etc. Any standards-compliant OIDC client library also works — point it at the discovery URL …/t/{tenant_slug}/.well-known/openid-configuration.
• Tutorials & context: Integration guide (step-by-step), Getting Started (first run + glossary), Technical overview (architecture & security model).
• Regenerate this inventory if the service changes: cd target && uv run python scripts/export_openapi.py.

Coverage: this reference documents the operations across 108 paths exposed by the service (including the feature-005 application-access/entitlement/admin-key endpoints, the feature-012 groups + tenant-administration endpoints, the feature-014 SSH-key endpoints, and the feature-015 appearance/branding surface). Not included (not implemented today): LDAP/AD login, OAuth device-code grant, and SAML SP-initiated AuthnRequest / Single Logout.