Appearance
Authentication API Reference
GET /.well-known/jwks.json
Fetch public signing keys
Use this public endpoint to validate teamusers EdDSA JWT signatures locally. API gateways and services call it and cache the returned key set by kid.
Responses
- 200 — Successful response
json
{
"keys": [
{
"alg": "EdDSA",
"crv": "Ed25519",
"kid": "01J8Z3KEY00000000000000001",
"kty": "OKP",
"use": "sig",
"x": "11qYAYL9f3rK3z7Z4Yj6d8bYJQ4mC3bX2h0qk8mVqB8"
}
]
}Errors
| Status | Code | Detail |
|---|---|---|
| 500 | jwks unavailable | Signing key set could not be encoded |
POST /auth/client-credentials
Obtain a service token
Use for service-to-service authentication. The caller presents the client ID (service user's username) and one-time secret created by POST /users/{id}/credentials with kind service.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| client_id | string | Yes |
| client_secret | string | Yes |
json
{
"client_id": "orders-service",
"client_secret": "generated-service-secret"
}Responses
- 200 — Successful response
json
{
"access_token": "eyJhbGciOiJFZERTQSIs...",
"expires_in": 600,
"refresh_token": "refresh-token-opaque",
"token_type": "Bearer"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 423 | account_locked | account_locked |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/introspect
Introspect an access or refresh token
Use from a trusted service to check whether a token is active without exposing token material. The caller must authenticate with a service-kind EdDSA bearer token; inactive or missing input still returns 200 with active false.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| token | string | No |
json
{
"token": "eyJhbGciOiJFZERTQSIs..."
}Responses
- 200 — Successful response
json
{
"active": true,
"exp": 1760000000,
"kind": "user",
"perm_ver": 3,
"sub": "01J8Z3USER000000000000001",
"team": "01J8Z3TEAM000000000000001"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/invite/accept
Accept an invitation
Use from an invitation email to set the initial password and activate the invited account. The invitation email is marked verified; display_name is optional.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| display_name | string | No |
| password | string | Yes |
| token | string | Yes |
json
{
"display_name": "Alice Example",
"password": "NewAtLeastTwelve1",
"token": "invitation-token-from-email"
}Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_token | invalid_token |
| 422 | weak_password | weak_password |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/login
Sign in with a password
Use when an end user needs an access and refresh token pair. Administrator-provisioned passwords instead return 403 password_change_required with a ten-minute change_token accepted only by POST /me/password; that endpoint still verifies the current password. Accounts with TOTP enabled or an effective required-MFA policy receive an initial MFA challenge, or a restricted MFA-enrollment token when required TOTP is not enrolled. Complete this login challenge at POST /auth/login/mfa; it is distinct from authenticated MFA-only step-up. Access tokens carry auth_time for primary authentication and may carry step_up_time only after POST /auth/step-up/complete; refresh preserves both.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| password | string | Yes |
| username | string | Yes |
json
{
"password": "AtLeastTwelve1",
"username": "alice"
}Responses
- 200 — Successful response
json
{
"mfa_methods": [
"otp"
],
"mfa_required": true,
"mfa_token": "eyJhbGciOiJFZERTQSIs..."
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | account_pending | account_pending; password_change_required; mfa_enrollment_denied |
| 403 | mfa_enrollment_denied | account_pending; password_change_required; mfa_enrollment_denied |
| 403 | password_change_required | account_pending; password_change_required; mfa_enrollment_denied |
| 423 | account_locked | account_locked |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/login/mfa
Complete MFA login
Use after password or passkey login returns mfa_required. Submit the short-lived MFA token and either a current TOTP code or one unused backup code. This completes initial login MFA, not MFA-only step-up; success returns the normal token pair with the primary-auth auth_time unchanged and additive amr claims.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| code | string | Yes |
| mfa_token | string | Yes |
json
{
"code": "123456",
"mfa_token": "eyJhbGciOiJFZERTQSIs..."
}Responses
- 200 — Successful response
json
{
"access_token": "eyJhbGciOiJFZERTQSIs...",
"expires_in": 600,
"refresh_token": "refresh-token-opaque",
"token_type": "Bearer"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 423 | account_locked | account_locked |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/login/mfa/enroll/begin
Begin required MFA enrollment
Use with the restricted mfa_token returned as mfa_enrollment_required when required TOTP is not enrolled. It authorizes only initial-login enrollment and returns a pending TOTP secret; it is not an access token. MFA-only step-up never enrolls a factor.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| code | string | No |
| mfa_token | string | Yes |
json
{
"mfa_token": "eyJhbGciOiJFZERTQSIs..."
}Responses
- 200 — Successful response
json
{
"otpauth_url": "otpauth://totp/teamusers:alice?secret=JBSWY3DPEHPK3PXP&issuer=teamusers",
"secret": "JBSWY3DPEHPK3PXP"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 409 | totp_already_enabled | totp_already_enabled |
| 423 | account_locked | account_locked |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/login/mfa/enroll/complete
Complete required MFA enrollment
Use after beginning required TOTP enrollment with the same restricted mfa_token. A valid code activates TOTP and returns backup codes with a full token pair whose amr includes otp and whose auth_time remains the primary authentication time. This initial enrollment flow is distinct from MFA-only step-up.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| code | string | No |
| mfa_token | string | Yes |
json
{
"code": "123456",
"mfa_token": "eyJhbGciOiJFZERTQSIs..."
}Responses
- 200 — Successful response
json
{
"access_token": "eyJhbGciOiJFZERTQSIs...",
"backup_codes": [
"abcd1234efgh5678"
],
"expires_in": 600,
"refresh_token": "refresh-token-opaque",
"token_type": "Bearer"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 409 | totp_already_enabled | totp_already_enabled |
| 423 | account_locked | account_locked |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/logout
Revoke a refresh-token family
Use when a client signs out. The operation is intentionally idempotent: missing, malformed, unknown, expired, or already-revoked refresh tokens produce 204 and do not disclose token state.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| refresh_token | string | Yes |
json
{
"refresh_token": "refresh-token-opaque"
}Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
GET /auth/oidc/begin
Begin OIDC login
When OIDC is configured, redirects to the configured issuer with single-use state, nonce, and PKCE S256 challenge. The state and nonce digests, challenge, and verifier are stored server-side for five minutes. The endpoint sets a Secure, HttpOnly, SameSite=Lax __Host-oidc_state cookie containing the state digest, with Path=/ and no Domain; Secure is unconditional because TLS terminates at the trusted proxy. The endpoint is rate-limited and responds with an HTTP 302 Location header rather than a JSON body.
Responses
- 200 — Successful response
Errors
| Status | Code | Detail |
|---|---|---|
| 404 | oidc_not_configured | OIDC Not Configured |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
GET /auth/oidc/callback
Complete OIDC login
Requires a matching state-digest cookie, consumes state once, and exchanges the authorization code with its PKCE verifier using a ten-second timeout. Verifies the signed ID token against cached issuer JWKS and validates issuer, audience, expiry, iat, nbf, and nonce; iat cannot be older than ten minutes or more than 30 seconds in the future, and nbf cannot be more than 30 seconds in the future. An unknown kid triggers a JWKS refresh. Email linking requires a locally verified email on a user that is not pending or invited; erased accounts are not linkable. Refused links return 403 oidc_link_refused. Returns a JSON token pair, or an initial MFA challenge after OIDC primary authentication when local MFA is required; it never redirects to a frontend.
Responses
- 200 — Successful response
json
{
"access_token": "signed-access-token",
"expires_in": 600,
"refresh_token": "opaque-refresh-token",
"token_type": "Bearer"
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 403 | account_pending | oidc_link_refused; registration_closed; account_pending; mfa_enrollment_denied |
| 403 | mfa_enrollment_denied | oidc_link_refused; registration_closed; account_pending; mfa_enrollment_denied |
| 403 | oidc_link_refused | oidc_link_refused; registration_closed; account_pending; mfa_enrollment_denied |
| 403 | registration_closed | oidc_link_refused; registration_closed; account_pending; mfa_enrollment_denied |
| 404 | oidc_not_configured | OIDC Not Configured |
| 423 | account_locked | account_locked |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/passkey/login/begin
Begin passkey login
Use to begin a WebAuthn assertion. Pass an optional username for a scoped ceremony, or an empty body for discoverable credentials; the browser passes the returned publicKey options to navigator.credentials.get.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| username | string | No |
json
{
"username": "alice"
}Responses
- 200 — Successful response
json
{
"publicKey": {
"allowCredentials": [
{
"id": "base64url-credential-id",
"type": "public-key"
}
],
"challenge": "base64url-challenge",
"rpId": "localhost",
"timeout": 300000
}
}Errors
| Status | Code | Detail |
|---|---|---|
| 401 | authentication failed | Unauthorized |
| 423 | account_locked | account_locked |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/passkey/login/finish
Finish passkey login
Use with the browser's PublicKeyCredential assertion response from the begin operation. A userVerified assertion can satisfy required MFA at primary login; this is separate from MFA-only step-up. Without user verification, enrolled TOTP triggers an initial MFA challenge; when TOTP is not enrolled, a required MFA policy yields a restricted enrollment token or, when deny_unenrolled is set, a 403 mfa_enrollment_denied. Without either TOTP or a required policy, login returns a full token pair. Successful access tokens include amr and primary-auth auth_time; only the separate step-up flow sets step_up_time.
Request body (application/json)
| Field | Type | Required |
|---|
json
{
"id": "base64url-credential-id",
"rawId": "base64url-credential-id",
"response": {
"authenticatorData": "base64url-authenticator-data",
"clientDataJSON": "base64url-client-data",
"signature": "base64url-signature"
},
"type": "public-key"
}Responses
- 200 — Successful response
json
{
"mfa_methods": [
"otp"
],
"mfa_required": true,
"mfa_token": "eyJhbGciOiJFZERTQSIs..."
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | invalid WebAuthn response | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | mfa_enrollment_denied | mfa_enrollment_denied |
| 423 | account_locked | account_locked |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/password-reset/confirm
Confirm a password reset
Use with the one-time token delivered by the notification service. The new password must satisfy policy; success revokes all sessions and clears lockout state.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| new_password | string | Yes |
| token | string | Yes |
json
{
"new_password": "NewAtLeastTwelve1",
"token": "reset-token-from-email"
}Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_token | invalid_token |
| 422 | weak_password | weak_password |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/password-reset/request
Request a password reset
Use when a user has lost a password. Submit a username or email; the endpoint always returns 204 so callers cannot enumerate accounts. A notification event is emitted only for an active matching account.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| login | string | Yes |
json
{
"login": "alice@example.test"
}Responses
- 204 — No Content
POST /auth/refresh
Rotate a refresh token
Use to obtain a fresh access/refresh pair without prompting the user for a password. Rotation revokes the presented token and stays within the same session family and original family_not_after cap. It preserves the primary-auth auth_time and any step_up_time unchanged; refresh never makes authentication fresh. Reuse or expiry invalidates the request and can revoke its whole family.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| refresh_token | string | Yes |
json
{
"refresh_token": "refresh-token-opaque"
}Responses
- 200 — Successful response
json
{
"access_token": "eyJhbGciOiJFZERTQSIs...",
"expires_in": 600,
"refresh_token": "refresh-token-rotated",
"token_type": "Bearer"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 401 | authentication failed | Unauthorized |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/register
Register a user
Use for public self-registration when registration mode is open or approval. A web or mobile client submits the profile and password; the service creates a pending account and sends an email verification notification. Closed mode rejects registration.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| display_name | string | No |
| string | Yes | |
| password | string | Yes |
| username | string | Yes |
json
{
"display_name": "Alice Example",
"email": "alice@example.test",
"password": "AtLeastTwelve1",
"username": "alice"
}Responses
- 200 — Successful response
json
{
"id": "01J8Z3USER000000000000001",
"status": "pending"
}Errors
| Status | Code | Detail |
|---|---|---|
| 400 | request body must be valid JSON | Invalid Request |
| 403 | registration_closed | registration_closed |
| 422 | weak_password | weak_password |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/step-up/begin
Begin MFA-only step-up
Use with an authenticated user bearer and its current refresh token after a guarded operation returns 403 step_up_required; this route is not freshness-guarded. The refresh token binds a persisted, purpose-specific, single-use challenge to the same user and session, and the step_up_token expires after five minutes. methods lists only currently enrolled, usable factors: otp for TOTP, backup_code for an unused backup code, and webauthn for a passkey. When webauthn is available, public_key is the direct user-bound assertion-options object with challenge, timeout, rpId, allowCredentials, and userVerification set to required (plus optional library extensions). This flow never enrolls a factor. Service and impersonation tokens return 403 step_up_forbidden; if no eligible factor is available, begin returns 403 step_up_not_available and the user must complete full primary login and any required enrollment instead. Accepts Idempotency-Key; the same key and body in the same raw Authorization scope replay the response, while a changed bearer uses a different scope. If canceled, abandon the challenge and let it expire.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| refresh_token | string | Yes |
json
{
"refresh_token": "<current refresh token for this user bearer>"
}Responses
- 200 — Successful response
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | refresh_token is required | Invalid Request; Invalid Request |
| 400 | request body must be valid JSON | Invalid Request; Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | step_up_forbidden | step_up_forbidden; step_up_not_available |
| 403 | step_up_not_available | step_up_forbidden; step_up_not_available |
| 409 | idempotency_in_progress | Idempotency In Progress |
| 422 | idempotency_conflict | Idempotency Conflict |
| 423 | account_locked | account_locked |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/step-up/complete
Complete MFA-only step-up
Use the step_up_token and same current refresh token supplied to POST /auth/step-up/begin, plus exactly one proof: code for TOTP or an unused backup code, or credential for the user-verified WebAuthn assertion serialized from navigator.credentials.get using the begin response's public_key options. The authenticated user bearer and challenge must match the refresh session. A valid proof atomically consumes the one-use challenge and proof, rotates the refresh token within the original session family without extending family_not_after, preserves primary-auth auth_time and amr, and adds step_up_time; normal refresh preserves both timestamps without making them newer. Failed factor proofs return 401 authentication failed without consuming the persisted challenge, proof, or refresh session, subject to rate limits and account lockout. step_up_not_available is begin-only. Replace both stored tokens only after success. Accepts Idempotency-Key: use a new key for a different proof because a same-key/same-body retry replays the prior response and the same key with a different body conflicts; a changed bearer uses a different raw Authorization scope. After an ambiguous network failure, do not automatically retry. If canceled, abandon the challenge and let it expire.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| code | string | No |
| credential | object | No |
| refresh_token | string | Yes |
| step_up_token | string | Yes |
json
{
"code": "123456",
"refresh_token": "<current refresh token for this user bearer>",
"step_up_token": "<step_up_token returned by begin>"
}Responses
- 200 — Successful response
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | exactly one of code or credential is required | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | invalid WebAuthn response | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | refresh_token and step_up_token are required | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | request body must be valid JSON | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | step_up_forbidden | step_up_forbidden |
| 409 | idempotency_in_progress | Idempotency In Progress |
| 422 | idempotency_conflict | Idempotency Conflict |
| 423 | account_locked | account_locked |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |
POST /auth/verify-email
Verify an email address
Use from the link or token delivered by the notification service after registration. It marks the account verified and, in open mode, activates it; approval mode still requires administrator approval.
Request body (application/json)
| Field | Type | Required |
|---|---|---|
| token | string | Yes |
json
{
"token": "verification-token-from-email"
}Responses
- 204 — No Content
Errors
| Status | Code | Detail |
|---|---|---|
| 400 | invalid_token | invalid_token |
| 429 | authentication temporarily busy | Too Many Requests |
| 500 | authentication service unavailable | Internal Server Error |