Auth API reference

Auth API · Consumer-Admin-Mfa

post/{app_slug}/v1/users/{user_id}/factorsAuth

Provision an MFA factor on behalf of a user

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`.

Path parameters

app_slug*string

Slug of the app.

user_id*string

Id of the user.

Headers

Idempotency-Keystring

Retry safety for factor enrolment. The first request returns the enrolment secret; a repeat with the same key and body returns 409 `idempotency_secret_not_replayable` with `details.factor_id` (the secret is never replayed: delete that factor and start again). Same key with a different body: 409 `IDEMPOTENCY_KEY_REUSE`. 24 h window.

Request body

type*enum (3)

Factor type to enrol: `totp`, `email` or `webauthn`.

Example: "totp"

labelstring

Optional human-readable label shown in the authenticator app and on the factor list (e.g. "iPhone 15").

contact_idstring · uuid

Email factors only: id of the verified email contact the codes should be delivered to. Defaults to the primary verified email. 412 when the contact (or the primary email) is unverified.

Response · 201

factor*object
id*string

Unique identifier of the factor.

type*string

Factor type — `totp` (authenticator app), `email` (single-use code delivered to a verified email contact), or `webauthn` (a passkey). Further factor types will extend this list without a breaking change to the response shape.

Example: "totp"

label*string

Label the user gave the factor, or `null`.

enabled*boolean

Whether the factor is enabled.

created_at*string · date-time

When the factor was created (ISO 8601).

enabled_at*string · date-time

When the factor was enabled (ISO 8601), or `null`.

enrollment*object

Type-specific enrollment payload for the new factor (the TOTP secret and `otpauth_uri` for `totp`; `email` factors need no payload beyond the bound contact). Shown once.

recovery_codes*array

Cleartext single-use recovery codes minted alongside the factor.

Example

Request

POST https://api.auth.productcraft.co/{app_slug}/v1/users/{user_id}/factors
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "type": "totp",
  "label": "string",
  "contact_id": "00000000-0000-0000-0000-000000000000"
}

Response

{
  "factor": {
    "id": "string",
    "type": "totp",
    "label": "string",
    "enabled": false,
    "created_at": "2026-01-01T00:00:00.000Z",
    "enabled_at": "2026-01-01T00:00:00.000Z"
  },
  "enrollment": {},
  "recovery_codes": [
    "string"
  ]
}