Auth API reference

Auth API · Consumer-Auth

post/{app_slug}/v1/auth/mfa/verify

Complete an MFA challenge with a TOTP or emailed 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.

Path parameters

app_slug*string

Slug of the app.

Request body

mfa_token*string

The `mfa_token` returned by `/auth/signin`. UUID.

Example: "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f"

codestring

A current TOTP code, or the emailed code requested via `/auth/mfa/send-code` (6 digits either way). Omit when submitting `credential`.

Example: "123456"

credentialobject

Passkey MFA: the `PublicKeyCredential` from `navigator.credentials.get()`, driven by the options from `/auth/mfa/webauthn/options`. ArrayBuffers base64url-encoded. Mutually exclusive with `code`.

Response · 200 MFA challenge completed; session + tokens minted.

result*object

Always `session` here: a session was minted. Discriminates the sign-in results (`session`, `mfa_required`, `mfa_enrollment_required`).

access_token*string

Short-lived JWT signed with the app-scoped JWKS key. Carries sub, role, permissions[], type=end_user.

refresh_token*string

Long-lived opaque-ish JWT used to mint a new access token via /auth/refresh. Rotated on use.

token_type*string

Always `Bearer`.

Example: "Bearer"

expires_in*number

Access-token lifetime in seconds.

Example: 3600

password_warningsarray

Non-fatal notes about the password that was just set. Present only on `signup` and `accept-invite`, and only when the app runs `password_breach_check: "warn"` and the password was found in a public breach corpus — the value is then `["breached"]` and the session is minted anyway, so the client can prompt the user to change it. The key is ABSENT (not an empty array) when there is nothing to report; do not branch on its length without checking that it exists. Apps on the default `block` never see it — a breached password is refused with 400 `PASSWORD_BREACHED`.

Example: ["breached"]

mfa_enrollment_due_atstring · date-time

Present only when the app runs `mfa: "required"`, the user holds no enabled factor, and the account is still inside `mfa_grace_days` of its creation. The session IS minted; this is the deadline after which sign-in will start returning `mfa_enrollment_required` instead, so a client can prompt rather than block. Absent in every other case.

Example

Request

POST https://api.auth.productcraft.co/{app_slug}/v1/auth/mfa/verify
Content-Type: application/json

{
  "mfa_token": "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f",
  "code": "123456",
  "credential": {}
}

Response

{
  "result": {},
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "Bearer",
  "expires_in": 3600,
  "password_warnings": [
    "breached"
  ],
  "mfa_enrollment_due_at": "2026-01-01T00:00:00.000Z"
}