Skip to content

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 ​

StatusCodeDetail
500jwks unavailableSigning 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) ​

FieldTypeRequired
client_idstringYes
client_secretstringYes
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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
423account_lockedaccount_locked
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
tokenstringNo
json
{
  "token": "eyJhbGciOiJFZERTQSIs..."
}

Responses ​

  • 200 — Successful response
json
{
  "active": true,
  "exp": 1760000000,
  "kind": "user",
  "perm_ver": 3,
  "sub": "01J8Z3USER000000000000001",
  "team": "01J8Z3TEAM000000000000001"
}

Errors ​

StatusCodeDetail
401authentication failedUnauthorized
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
display_namestringNo
passwordstringYes
tokenstringYes
json
{
  "display_name": "Alice Example",
  "password": "NewAtLeastTwelve1",
  "token": "invitation-token-from-email"
}

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
400invalid_tokeninvalid_token
422weak_passwordweak_password
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
passwordstringYes
usernamestringYes
json
{
  "password": "AtLeastTwelve1",
  "username": "alice"
}

Responses ​

  • 200 — Successful response
json
{
  "mfa_methods": [
    "otp"
  ],
  "mfa_required": true,
  "mfa_token": "eyJhbGciOiJFZERTQSIs..."
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
403account_pendingaccount_pending; password_change_required; mfa_enrollment_denied
403mfa_enrollment_deniedaccount_pending; password_change_required; mfa_enrollment_denied
403password_change_requiredaccount_pending; password_change_required; mfa_enrollment_denied
423account_lockedaccount_locked
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
codestringYes
mfa_tokenstringYes
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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
423account_lockedaccount_locked
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
codestringNo
mfa_tokenstringYes
json
{
  "mfa_token": "eyJhbGciOiJFZERTQSIs..."
}

Responses ​

  • 200 — Successful response
json
{
  "otpauth_url": "otpauth://totp/teamusers:alice?secret=JBSWY3DPEHPK3PXP&issuer=teamusers",
  "secret": "JBSWY3DPEHPK3PXP"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
409totp_already_enabledtotp_already_enabled
423account_lockedaccount_locked
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
codestringNo
mfa_tokenstringYes
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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
409totp_already_enabledtotp_already_enabled
423account_lockedaccount_locked
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
refresh_tokenstringYes
json
{
  "refresh_token": "refresh-token-opaque"
}

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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 ​

StatusCodeDetail
404oidc_not_configuredOIDC Not Configured
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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 ​

StatusCodeDetail
401authentication failedUnauthorized
403account_pendingoidc_link_refused; registration_closed; account_pending; mfa_enrollment_denied
403mfa_enrollment_deniedoidc_link_refused; registration_closed; account_pending; mfa_enrollment_denied
403oidc_link_refusedoidc_link_refused; registration_closed; account_pending; mfa_enrollment_denied
403registration_closedoidc_link_refused; registration_closed; account_pending; mfa_enrollment_denied
404oidc_not_configuredOIDC Not Configured
423account_lockedaccount_locked
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
usernamestringNo
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 ​

StatusCodeDetail
401authentication failedUnauthorized
423account_lockedaccount_locked
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
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 ​

StatusCodeDetail
400invalid WebAuthn responseInvalid Request
401authentication failedUnauthorized
403mfa_enrollment_deniedmfa_enrollment_denied
423account_lockedaccount_locked
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
new_passwordstringYes
tokenstringYes
json
{
  "new_password": "NewAtLeastTwelve1",
  "token": "reset-token-from-email"
}

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
400invalid_tokeninvalid_token
422weak_passwordweak_password
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
loginstringYes
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) ​

FieldTypeRequired
refresh_tokenstringYes
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 ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
401authentication failedUnauthorized
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
display_namestringNo
emailstringYes
passwordstringYes
usernamestringYes
json
{
  "display_name": "Alice Example",
  "email": "alice@example.test",
  "password": "AtLeastTwelve1",
  "username": "alice"
}

Responses ​

  • 200 — Successful response
json
{
  "id": "01J8Z3USER000000000000001",
  "status": "pending"
}

Errors ​

StatusCodeDetail
400request body must be valid JSONInvalid Request
403registration_closedregistration_closed
422weak_passwordweak_password
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
refresh_tokenstringYes
json
{
  "refresh_token": "<current refresh token for this user bearer>"
}

Responses ​

  • 200 — Successful response

Errors ​

StatusCodeDetail
400refresh_token is requiredInvalid Request; Invalid Request
400request body must be valid JSONInvalid Request; Invalid Request
401authentication failedUnauthorized
403step_up_forbiddenstep_up_forbidden; step_up_not_available
403step_up_not_availablestep_up_forbidden; step_up_not_available
409idempotency_in_progressIdempotency In Progress
422idempotency_conflictIdempotency Conflict
423account_lockedaccount_locked
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
codestringNo
credentialobjectNo
refresh_tokenstringYes
step_up_tokenstringYes
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 ​

StatusCodeDetail
400exactly one of code or credential is requiredInvalid Request; Invalid Request; Invalid Request; Invalid Request
400invalid WebAuthn responseInvalid Request; Invalid Request; Invalid Request; Invalid Request
400refresh_token and step_up_token are requiredInvalid Request; Invalid Request; Invalid Request; Invalid Request
400request body must be valid JSONInvalid Request; Invalid Request; Invalid Request; Invalid Request
401authentication failedUnauthorized
403step_up_forbiddenstep_up_forbidden
409idempotency_in_progressIdempotency In Progress
422idempotency_conflictIdempotency Conflict
423account_lockedaccount_locked
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal 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) ​

FieldTypeRequired
tokenstringYes
json
{
  "token": "verification-token-from-email"
}

Responses ​

  • 204 — No Content

Errors ​

StatusCodeDetail
400invalid_tokeninvalid_token
429authentication temporarily busyToo Many Requests
500authentication service unavailableInternal Server Error