Auth Consumer API.

Cursor-paginated. Supports the same `status` and `search` filters as the auth-admin equivalent. Use the cursor in subsequent calls — Auth does not expose offset pagination.

Create an account in this app. Distinct from the public `/auth/signup`: no session is issued, no password is required (when omitted, the customer triggers a password-reset to finish onboarding), and the primary email contact starts unverified — the customer is responsible for kicking off the verification flow via `/auth/request-verification` or `/auth/send-verification-email`. The `roleName` defaults to the app's `signup_default_role`. What is NOT distinct: the password policy. A supplied `password` goes through the same app-configured rules, the same common-password deny-list and the same breach check as `/auth/signup`.

Email update promotes an existing contact to primary (not for creating new contacts — that goes through the per-contact flow).

Removes the account, its sessions, contacts, and tenant memberships. Audit rows are preserved, and the deletion itself is audited as `auth.account.deleted` with `via: consumer_admin` and the caller as actor. Fires `user.deleted` with `via: "consumer_admin"`.

Setting status to `suspended` or `deactivated` also revokes all active sessions for the user (same behaviour as the auth-admin equivalent).

Sets `app_membership.role_id` for the target user. For M2M callers the assignable role is bounded by the token's scopes (the guard already enforced `role.assign`); the role's own permission set is NOT additionally narrowed against the M2M scopes because M2M scopes are typically broader than per-user role perms by design (a backend cron with `user.list` + `role.assign` SHOULD be able to promote a user into a role carrying any per-app perm). EndUser admins are bounded by their own role's perms transitively — they couldn't authenticate as an admin without holding the perm.

Creates the factor in the enabled state. TOTP: returns the cleartext secret + otpauth URI + recovery codes in the response — intended for synthetic-account-style flows where the caller bundles credentials and ships them out once. Email: binds the user's verified email contact (primary by default, `contact_id` to override; 412 when unverified) and returns the masked address + recovery codes — sign-in codes are then delivered on demand via `/auth/mfa/send-code`.

Returns the union of system permissions (shared across every app — `is_system: true` in the response) and any custom entries this app has defined (`is_system: false`). Useful for driving a role-editor UI that picks from the full catalogue.

Inserts a `<resource>.<action>` row in the per-app permission catalogue. The resource and action segments must each match `^[a-z][a-z0-9_-]{1,47}$`. Conflicts with a system permission name return 409. Customers usually then bind the new permission to a role via `PUT /admin/roles/:roleName/permissions`.

The `permissionKey` path parameter is the literal `<resource>.<action>` string. System permissions cannot be deleted — attempts return 403. Removing a permission also removes every `role_permission` row that bound it (cascade); role lookups dropped of that perm on the next request.

Cursor-paginated by `created_at`. Use the returned `next_cursor` in subsequent calls — offset pagination is not exposed.

Creates a role with no permissions bound yet. Use `PUT /:roleName/permissions` to attach a permission set after creation — that route also runs caller-narrowing so an EndUser admin can't grant verbs they don't themselves hold.

Returns the role plus the flat `permissions[]` array currently bound. Use this to drive a "configure role" UI in the customer product without having to call `/permissions` separately.

Renames are intentionally NOT supported — the role name is part of every issued EndUser JWT, so changing it would silently break live sessions. Create a new role and migrate users instead.

System roles (`owner`, `admin`, `member`) cannot be deleted — attempts return 403. Roles currently assigned to any member return 409 `ROLE_IN_USE`; reassign the affected members first.

Destructive — the role's permission set is replaced wholesale with the supplied array. Caller-narrowed: the caller must hold every permission in the request, otherwise 403 `Cannot grant actions you don't have: ...`. For EndUser callers the caller-held set is their app-membership role's effective permissions. For M2M callers the held set is the token's `scopes[]` claim — the M2M cannot grant a role any verb that wasn't configured on the M2M credential. Unknown permission strings return 400.

Create an EndUser account inside the app and immediately mint a session. The supplied email becomes the primary email contact, unverified at signup. When the app has completed Mail notification setup, a verification code is auto-emailed to the address; customers delivering their own verification messages call /auth/request-verification (or /auth/send-verification-email) instead — doing so invalidates the auto-sent code, so the user only ever has one valid code. Subject to the app-configured signup policy (signup enabled, password policy, default role, optional `signup_requires_pak`). The password must clear the app's length + character-class rules, a common-password deny-list, and — unless the app sets `password_breach_check` to `warn` or `off` — a public breach corpus; a breached password is refused with 400 `PASSWORD_BREACHED` and a deny-listed one with 400 `PASSWORD_TOO_COMMON`. The breach lookup is k-anonymous (only five characters of the password's SHA-1 leave the service) and fails open, so an unreachable corpus never blocks a signup. When the app runs `auth_config.mfa: "required"`, the account is still created but NO session is minted: the response is the `ConsumerMfaEnrollmentRequiredResponseDto` shape (`mfa_enrollment_required: true`), completed via `POST /auth/mfa/enroll` + `/auth/mfa/enroll/verify`. Inside `mfa_grace_days` of account creation — which a fresh signup always is when the window is non-zero — the ordinary token pair is returned with `mfa_enrollment_due_at` set instead. When the app has bot protection on (`auth_config.bot_protection`, Cloudflare Turnstile or hCaptcha), send the widget response as `bot_protection_token`. Auth verifies it with the provider before it looks at the email, username or password, and refuses the sign-up when the token is missing (400 `BOT_PROTECTION_REQUIRED`), rejected (403 `BOT_PROTECTION_FAILED`) or cannot be checked (503 `BOT_PROTECTION_UNAVAILABLE`; no account is created). This applies to PAK-authenticated calls too: a backend forwards the token its browser received.

Materialises a pre-allocated invite into a real EndUser: creates account + primary email contact (verified, since mailing the code proved control) + password credential + role membership, then mints app-scoped tokens. Public endpoint — the invite code is the authority. 410 on revoked/expired/exhausted invites; 409 on duplicate email or username. The same password policy as `/auth/signup` applies, including the common-password deny-list and the breach check, and so does the app-level MFA mandate: on an `auth_config.mfa: "required"` app the account is created but the response is `mfa_enrollment_required: true` with no session behind it.

Materialises a pending `tenant_invite` into a real EndUser: creates account + verified primary email contact (mailing the code proved control of the address) + password credential + an app-level membership on the app's signup default role + a tenant membership on the role the invite names, then mints a session already scoped to that tenant, so the access token carries `org_id` / `org_role` with no follow-up switch-tenant call. Public endpoint — the invite code is the authority. 410 on revoked/expired/exhausted invites. **409 when an account already exists for the invited address**: this endpoint will not set a password on, or mint a session for, an account it did not create, because the plaintext code is also held by whoever minted the invite. Existing users sign in and call `POST /:appSlug/v1/me/tenant-invites/accept` instead, which adds the membership without touching credentials.

Authenticate with username or verified primary email + password. When the account has no enabled MFA factors, returns a fresh access + refresh token pair (`ConsumerTokenResponseDto` shape). When the account has any enabled factor, returns an MFA challenge instead (`ConsumerMfaChallengeResponseDto` shape, `mfa_required: true`). In that case no session has been created yet — complete the challenge via `POST /auth/mfa/verify` (or `/auth/mfa/recover`) to receive the token pair. When the app runs `auth_config.mfa: "required"` and the account has NO enabled factor, returns a third shape (`ConsumerMfaEnrollmentRequiredResponseDto`, `mfa_enrollment_required: true`) — again no session — which is completed via `POST /auth/mfa/enroll` + `/auth/mfa/enroll/verify`. Inside `mfa_grace_days` of account creation that case instead returns the ordinary token pair with `mfa_enrollment_due_at` set.

Delivers a single-use 6-digit code to the masked address of an `email` factor listed on the challenge. Submit the code via `/auth/mfa/verify`. Requires the `mfa_token` from the signin response — possession of it (i.e. a correct password) is the authority. Throttled per challenge: max 3 sends, 30s between sends; each send supersedes the prior code.

Submit the `mfa_token` from a `mfa_required: true` signin response, plus EITHER a `code` (a current TOTP code, or the emailed code requested via `/auth/mfa/send-code`) OR a `credential` (a passkey assertion for the options from `/auth/mfa/webauthn/options`). Mints session + tokens with `amr: ["pwd", "<factor type>"]` and `mfa_at` set to now. The challenge is single-use; 5 wrong attempts locks it.

Mints a single-use WebAuthn challenge scoped to the account behind `mfa_token` and returns the `publicKey` member for `navigator.credentials.get()`. Submit the result to `/auth/mfa/verify` as `credential` instead of `code`. Possession of the `mfa_token` (i.e. a correct password) is the authority — nothing here reveals whether an account exists or holds passkeys until that token has been presented.

Returns a single-use WebAuthn challenge for `navigator.credentials.get()`. `allowCredentials` is ALWAYS empty and the response is shaped identically for every caller: this endpoint does not take an identifier and does not look one up, because returning a credential list for a registered address and an empty list for an unregistered one would be a single-request account-existence oracle. Sign-in therefore requires a discoverable (resident) credential — the authenticator finds its own passkey for the relying-party id. Submit the result to `/auth/passkey/verify`.

Verifies the assertion against the challenge from `/auth/passkey/options` and mints a session. The authenticator MUST have performed user verification (biometric / PIN) — a presence-only tap is refused on this path whatever the app policy says, because the passkey is the only authentication happening. Tokens carry `amr: ["webauthn"]` and a fresh `mfa_at`, so a passkey sign-in satisfies MFA-recency policies without a second step.

Same flow as `/auth/mfa/verify` but consumes a single-use recovery code (16 hex chars; hyphens optional). Mints tokens with `amr: ["pwd","recovery_code"]`. After successful recovery, the user should regenerate their recovery codes via `/me/mfa/recovery-codes/regenerate`.

For apps running `auth_config.mfa: "required"`. When a user proves their password but holds no enabled factor, `/auth/signin` returns `{ mfa_enrollment_required: true, mfa_token, expires_at }` and mints NO session; this endpoint starts the enrolment that `mfa_token` authorises. Same body and same response as `POST /{app_slug}/v1/me/mfa/factors`, but authenticated by the token rather than by a session — there is no session yet. TOTP returns the otpauth URI, QR data URL and shared secret; email sends a 6-digit code to the bound verified contact. The factor stays disabled until `/auth/mfa/enroll/verify` succeeds. The token is single-purpose: `/auth/mfa/verify`, `/auth/mfa/send-code` and `/auth/mfa/recover` all refuse it with 401, it is not an access token so `/me/*` refuses it, and `/auth/refresh` does not accept it.

Completes the flow started by `/auth/mfa/enroll`. TOTP: submit two `codes` from consecutive 30-second windows. Email: submit the emailed 6-digit `code`. On success the factor is enabled, a fresh set of recovery codes is minted and returned ONCE (invalidating any prior set), and the session sign-in withheld is finally minted with `amr: ["pwd","mfa"]` and `mfa_at` set to now. A wrong code counts against the token exactly as it does on the sign-in challenge; 5 failures lock it and the user must sign in again.

Rotates the refresh token on every call — the previous refresh token is revoked, and re-using it triggers session revocation.

Destroys the session that owns the refresh token. The matching access token continues to verify until its TTL expires.

Mints a fresh 6-digit verification code bound to the email or phone contact named in the body. Body must contain exactly one of `email` / `phone`. PAK-required — `Authorization: Bearer <pcft_live_*>` carrying `auth.user.verify.create` narrowed to this app's URN. Public mint flows are refused with 401 — any anonymous mint endpoint is a spam-forwarder vector. Returns `{ code, expires_at }` for delivery via the customer's own SMTP / SMS provider. Returns `{}` (no code) when the contact doesn't match an account in this app or is already verified — uniform shape prevents enumeration. Issuing a code invalidates any previously issued, unconsumed code for the same contact — including the one auto-emailed at signup. Only the most recently minted code is accepted.

Mints a fresh 6-digit verification code AND dispatches it to the supplied email address via the workspace's verified Mail sender, in one call. Email-only — the customer integrates SMS delivery themselves through `request-verification`. PAK-required — distinct permission from the bare mint so customers can enable mint without enabling outbound Mail traffic. Surfaces typed precondition errors instead of the silent fail-closed of a fire-and-forget mailer: * 412 ENVOI_NOT_ENABLED — `notifications_via_envoi` is false * 412 ENVOI_SENDER_NOT_CONFIGURED * 412 ENVOI_TEMPLATE_NOT_CONFIGURED * 412 ENVOI_APP_NOT_BOUND_TO_WORKSPACE * 503 ENVOI_DISPATCH_FAILED — RabbitMQ publish failure * 503 ENVOI_NOT_WIRED — no Mail client wired in this deployment On success returns `{ expires_at }`. The plaintext code is NOT returned. Returns `{}` when the contact is missing or already verified (silent — same enumeration defence as `request-verification`). Issuing a code invalidates any previously issued, unconsumed code for the same contact — including the one auto-emailed at signup. Only the most recently minted code is accepted.

Consumes a 6-digit verification code (single-use) and flips the bound contact's `verified_at`. Public — anyone holding the code can submit it; that is the whole point of the verification flow. The server figures out which contact + account from the code value itself. Renamed from /verify-email — the same endpoint now serves both email and phone verifications.

Mints a fresh 6-digit password-reset code for the EndUser owning the named contact. Body must contain exactly one of `email` / `phone` — the contact must be verified (otherwise an attacker who registered an unverified contact could push a reset on another user's account, were the per-app email uniqueness ever breached). The reset itself is account-scoped (revokes all sessions, replaces password) — the contact only acts as the lookup key. PAK-required: `auth.user.password-reset.create`. Returns `{ code, expires_at }` on success, `{}` on no-match (uniform shape prevents enumeration). Issuing a reset code invalidates any previously issued, unconsumed reset code for the account — only the most recent one is accepted. Renamed from /auth/request-reset.

Same shape as `send-verification-email` but for the reset slot. PAK perm: `auth.user.password-reset.send-email`. Same loud precondition errors. Email-only.

Consumes the 6-digit reset code (single-use). On success the password is updated and every active session for the user is revoked.

Re-issues the EndUser's access + refresh tokens with the new `org_id` + `org_role` claims, after verifying the caller holds a tenant_membership for the target tenant. The session row is updated to the new tenant so subsequent refreshes preserve the context. The new access token keeps the session's `amr` and `mfa_at` (as `/auth/refresh` does), so a sign-in that completed MFA still proves it after a switch. Refresh-token rotation runs as usual; the previous refresh token enters the standard 60-second grace window.

Returns each tenant the caller is a member of, including the tenant slug + display name and the member's role. Powers a tenant-switcher UI on the customer's product.

Includes factors in any state (pending enrollment + enabled). Disabled factors are not listed.

Creates a pending factor and returns the type-specific enrollment payload. TOTP: the otpauth URI, QR data URL, and shared secret; confirm with two consecutive codes. Email: a 6-digit code is sent to the bound verified email contact (primary by default, `contact_id` to override); confirm with that single code. The factor stays disabled until `/factors/:id/verify` succeeds.

TOTP: submit two `codes` from consecutive 30-second windows. Email: submit the emailed 6-digit `code`. On success the factor flips to enabled, recovery codes are minted (returned once), and prior recovery codes for the account are invalidated. Subsequent calls with the same `:id` fail with 400.

Soft-disable. The row is preserved (with `disabled_at` set) for audit. Has no effect on existing sessions — their `amr` claim still reflects whatever satisfied sign-in at the time. Disabling the only enabled factor removes the MFA requirement on future sign-ins.

Mints a fresh set of single-use recovery codes and invalidates every prior code for the account. The new codes are returned once — store them now.

Mints a single-use 6-digit code against one of the account's enabled email factors and delivers it to the bound address. Follow with `/step-up` submitting the code. Codes expire after 5 minutes; sends are throttled per contact (30s between sends, shared with the sign-in path). Refused while step-up is locked on this session.

Mints a single-use WebAuthn challenge for the enabled passkeys on this account and returns the `publicKey` member for `navigator.credentials.get()`. Submit the result to `/step-up` as `credential`. Refused while step-up is locked on this session — a locked session must not be able to keep minting challenges.

Verify a fresh code (TOTP, emailed via `/step-up/send-code`, or recovery) against any enabled factor on the account, and update the session's `auth_methods` + `mfa_at`. Call `/auth/refresh` after this to mint a token whose claims reflect the new state. Customers reading `mfa_at` from access tokens to gate sensitive actions should require a `/step-up` + refresh cycle when the timestamp is older than their policy window. 5 consecutive wrong codes lock step-up on this session for 15 minutes.

Adds the caller to the invited tenant with the role the invite names, and consumes the invite. Requires the invited address to be one of the caller's own VERIFIED email contacts in this app — holding the code is not sufficient, because whoever minted the invite also holds it, and an unverified contact is not proof of owning the address. A refused accept leaves the invite redeemable.

Returns the EndUser identity, app membership, and role name. The flat `permissions[]` array is intentionally NOT included — permissions resolve from the role on demand. Call `GET /me/permissions` for the flat list when the client needs it for UI gating.

Editable fields: `display_name` and `username`. The username is unique per app (case-insensitive, same rule as signup); sending the current username is a no-op. Usernames cannot be cleared.

Removes the EndUser, all sessions, and all related records inside this app. Cannot be undone. The app audit log keeps one `auth.account.deleted` row (`via: self`; username and email domain only, never the address), and `user.deleted` fires with `via: "self"`.

Returns the union of the app-level role permissions and the tenant-level role permissions (when the token carries an `org_id`). Resolved per-request through a 60-second LRU — role-permission edits propagate within ~1 minute. Use this instead of decoding a `permissions[]` claim from the JWT, which is no longer included. M2M tokens cannot call this — use `POST /:appSlug/v1/oauth/introspect` to inspect M2M scopes.

PNG/JPEG/WEBP only — SVG is rejected (stored-XSS vector). ≤2 MB. Magic bytes are sniffed; a mislabeled file is rejected. The image is re-encoded server-side (orientation baked in, all metadata incl. EXIF/GPS stripped, bounded to 512×512, webp). An uploaded avatar takes precedence over a provider-captured picture.

Clears both the uploaded avatar and any provider-captured picture, and deletes the stored object. A later Google/GitHub sign-in re-populates the provider picture — that is "sync from provider" behavior, by design.

Verifies `current_password`, sets the new hash, and revokes every OTHER active session for the account (the calling session is preserved). 401 if the current password is wrong or the account has no password credential — admin-provisioned accounts without an initial password should use the reset flow instead. The new password is held to exactly the same policy as signup: the app's length + character-class rules, the common-password deny-list, and the breach corpus.

Each session includes a `current` flag identifying the one belonging to the bearer token used for this request.

Sign the EndUser out of one device. The session's refresh token is destroyed; its access token expires on its TTL. Requires the `session.revoke` permission when the app's `enforce_app_permissions` flag is on; otherwise (the default) any valid token can call this. Self-revoke (revoking your own session as a member with no perms) is something to enforce separately if needed; this guard does not exempt the principal from the role check.

Login events, password changes, and other security-relevant records, scoped to this EndUser.

Adds an email or phone contact to the EndUser. The contact starts unverified and non-primary. Verification is a separate flow — call /auth/request-verification with the contact value and the customer's PAK to mint a code, then submit via /auth/verify.

Demotes the previous primary of the same type. Refused (409) when the target contact is unverified — promoting an unverified contact would let an attacker who registered the contact bypass verification by routing reset codes through it.

Stable, non-expiring URL for an EndUser avatar. 302s to a short-lived presigned GET for an uploaded avatar, or to the identity provider picture URL. Public — no auth; the account UUID is the capability. Responses are cacheable for 60 seconds.

Standard OAuth 2.0 client_credentials grant. Returns an app-scoped access token whose `scopes[]` claim is the union of the client's configured scopes. Use for service-to-service calls.

OAuth 2.0 token introspection. Send the access token via `Authorization: Bearer <token>` and receive either `{ active: false }` (invalid / expired / wrong app, or a session that is revoked, past its `expires_at`, or gone because the end user was deleted) or the active claim set including `scopes` (M2M) or `role` (EndUser), `exp`, `iat`, `iss`, `aid`. The body `token` field is optional and, if present, must match the bearer — RFC 7662 allows a separate `token` body field but we deliberately refuse cross-token introspection so a stolen token can't be probed against another active credential. The endpoint accepts both M2M and EndUser tokens — use it as the canonical way for a service to know what its own token can do, instead of decoding the JWT by hand. Returns 401 when the bearer is missing.

Submit the provider-issued ID token from a native client (iOS ASAuthorizationController, Google Sign-In for iOS / Android). Backend verifies the token signature, issuer, audience (against this app's configured native client ids), and nonce binding; consumes the nonce server-side to defeat in-window replay; resolves or creates the Auth account; mints access + refresh tokens with `amr=["oauth", "<provider>"]`. Same response shape as `/auth/signin`.

For your backend: is this `pctk_` key, presented to YOUR API, usable right now, for which tenant and with which scopes? A key of another app is `{"active": false}`. Cache answers by the key's SHA-256: positives up to 30 s (never past `expires_at`), negatives up to 60 s. Intersect `scopes` with the permissions of `created_by.tenant_role` in your app. Requires `auth.tenant.api_keys.introspect` on the app. Not audited per call; `last_used_at` records use (5-minute granularity). This route has its own per-app rate bucket (1200 calls a minute by default), separate from your PAK's other calls; over it the answer is 429 with `Retry-After`, never a false `active: false`, so keep serving keys you hold a fresh positive for.

Requires `auth.tenant.api_keys.configure` on the app.

Call it on boot: your code is the source of truth for the scopes a key can carry. Fields you leave out keep their stored value. `suspended` is the platform's kill switch: this route never changes it, and a body that carries it is refused. Requires `auth.tenant.api_keys.configure` on the app.

For your own audit trail: record why a key you saw go inactive died (revoked in the console, creator left the tenant, expired, keys suspended). Only keys of this app; another app's key is 404. Requires `auth.tenant.api_keys.introspect` on the app.

Newest first, cursor-paginated (20 per page, max 100). Secrets are never returned; `key_prefix` and `last4` identify a key.

Returns the secret ONCE (`key`). Scopes must be grantable by the app and held by your own tenant role. At most 25 active keys per tenant. If the app requires recent MFA, verify a factor first (403 `step_up_required`). Responses carry `Cache-Control: no-store`.

Mints a replacement with the same name and scopes and returns its secret ONCE. You become the replacement's creator, so its scopes must be within your own tenant role. The outgoing key is revoked now (`grace_hours: 0`, the default) or keeps working for up to 24 hours. To kill a leaked key, revoke it. Responses carry `Cache-Control: no-store`.

Immediate and final. Idempotent: revoking a revoked key is a 204 that changes nothing.