HAP - Detailed User Guide

A capability-by-capability reference for using the Headless Auth Platform. It assumes you can run the service and have an admin key — start with Getting started for first-run and a glossary, and the Integration guide for the core login flow. To run HAP on your own machine (e.g. to authenticate apps you develop locally), see Local login guidelines — a Docker-CLI quickstart for the published image. Endpoints are per-tenant under /t/{tenant_slug}/…; admin endpoints use X-Admin-Key (+ X-Tenant-Id).

Everything below is available today. See Roadmap for what isn't yet.

1. Tenants, applications & providers (admin)

Create a tenant — POST /v1/tenants (platform admin). Generates the tenant's signing key and a default role; its discovery document then resolves at /t/{slug}/.well-known/openid-configuration.
Create an application — POST /v1/applications (tenant admin). Returns a client_id; confidential clients (web, machine_to_machine) also get a one-time client_secret. Set redirect_uris (matched exactly) and scopes.
Create an identity provider — POST /v1/providers for social/OIDC or SAML, including a SCIM bearer token when SCIM is enabled.

2. Identities & passwords

Register — POST /v1/auth/register (enforces the tenant password policy).
Verify email — POST /v1/auth/verify-email/request then /confirm with the token.
Reset password — POST /v1/auth/password-reset/request (always returns the same response — no account enumeration) then /confirm; a successful reset revokes existing sessions.
Admin user management — GET/POST/PATCH/DELETE /v1/identities (scoped admin key); responses never include credential material; delete is a soft-delete with PII erasure.
Behind the scenes: passwords use Argon2id; repeated failures lock the account for a configurable window; legacy hashes are upgraded on next login.

3. Logging in & tokens (OAuth 2.0 / OIDC)

The core flow — discovery → login → authorize (PKCE) → token → user-info — is documented step-by-step in the Integration guide. Key points:

Grants: authorization_code, refresh_token, client_credentials.
PKCE S256 is mandatory; redirect URIs must match exactly.
Refresh-token rotation: each use issues a new refresh token; reusing an old one is treated as theft and revokes the whole token family.
Introspection / revocation: POST /oauth2/introspect and /oauth2/revoke.

4. Sessions & step-up (AAL)

List your sessions — GET /v1/sessions (with a bearer access token); each shows device and location context.
Revoke one / all — DELETE /v1/sessions/{id} and DELETE /v1/sessions ("log out everywhere"). Admins can revoke all sessions for any identity.
Step-up: when an action requires a higher assurance level than the session holds, the authorize endpoint returns interaction_required with required_acr (e.g., aal2). After the user completes a second factor, the same session is elevated — no fresh login.

5. Multi-factor authentication (MFA)

TOTP (authenticator app): POST /v1/mfa/totp/enroll → show the otpauth_uri/secret → POST /v1/mfa/totp/confirm with a code. Later, POST /v1/mfa/totp/verify raises the session to AAL2. Codes can't be reused within their window.
Email/SMS one-time passcodes: POST /v1/mfa/otp/send {channel} then POST /v1/mfa/otp/verify. Issuance is rate-limited; codes expire and lock after too many attempts.

6. Passkeys (WebAuthn / FIDO2)

Register: POST /v1/webauthn/register/begin → your client performs the WebAuthn ceremony → POST /v1/webauthn/register/finish.
Log in (incl. usernameless): POST /v1/webauthn/login/begin → ceremony → POST /v1/webauthn/login/finish, which creates a session (AAL2 when user-verified).
Clone protection: the signature counter must increase; a cloned authenticator is detected and the credential is flagged.

Social / OIDC login: GET /v1/providers/{id}/login returns the upstream redirect URL; after the user returns, GET /v1/providers/{id}/callback links to an existing identity (by verified email or provider subject) or just-in-time provisions a new one.
Enterprise SSO (SAML SP): post a signed SAML assertion to /v1/saml/{id}/acs; the platform validates the signature, audience, expiry, and replay, then provisions per verified domain. SP metadata is at /v1/saml/{id}/metadata.
Platform as IdP: POST /v1/saml/issue issues a signed SAML assertion (with identity + application custom claims) to a downstream SAML service-provider application.

8. Authorisation (RBAC)

Roles: POST /v1/rbac/roles (name + permissions). Assign/revoke: POST/DELETE /v1/identities/{id}/roles. Effective permissions (union of active, non-expired assignments) are embedded in the access token's permissions claim.

9. AI-native risk

Every login attempt is scored from contextual signals (new device, unusual location, impossible travel, velocity, credential-stuffing patterns). Under an adaptive tenant policy the result maps to allow / challenge / block.
Breached-password check: enable it in the tenant password policy; passwords are checked against known-breached corpora via a privacy-preserving range query (only a partial hash prefix ever leaves the system).
Security suggestions: GET /v1/ai/suggestions, then accept/dismiss.

10. Operations

Webhooks: POST /v1/webhooks (returns a signing secret once). Deliveries are HMAC- signed (X-HAP-Signature), retried with backoff, and auto-disabled after repeated failure.
SCIM 2.0: /scim/v2/Users (create / get / patch active / delete), bearer-authenticated per provider, to sync users from a company directory.
Audit & SIEM: every mutating action is written to an append-only, time-partitioned audit log that can be streamed to an external sink.

Roadmap (not yet available)

LDAP/AD direct login; OAuth device-code grant; formal compliance certification (today: supporting controls and audit evidence); SAML SP-initiated AuthnRequest & single logout; live session-anomaly step-up; audit retention age-out; login-endpoint rate limiting; scoped admin-key issuance; fully asynchronous notification delivery.