Enroll TOTP using an MFA challenge (no JWT required)

POST

/v1/auth/mfa/enroll-via-challenge

curl --request POST \
  --url https://example.com/v1/auth/mfa/enroll-via-challenge \
  --header 'Content-Type: application/json' \
  --data '{ "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "action": "generate", "code": "example" }'

Used when a tenant requires MFA but the user hasn’t enrolled yet. The user receives a challenge_id from VerifyMFAChallenge (enrollment_required=true), then calls this endpoint to generate a TOTP secret, enroll it, and get a JWT. The challenge_id serves as the credential — no JWT is needed.

Request Body ^required

Media type application/json

object

challenge_id

required

string format: uuid

action

required

‘generate’ returns a TOTP secret/QR URI. ‘verify’ validates the code and completes enrollment.

string

Allowed values: generate verify

code

TOTP code from the authenticator app. Required when action is verify.

string

Responses

200

Enrollment step completed.

Media type application/json

object

secret

TOTP shared secret for manual entry. Only on generate action.

string

nullable

qr_uri

Otpauth:// URI for QR code. Only on generate action.

string

nullable

token

Signed JWT. Only on successful verify action.

string

nullable

expires_at

string format: date-time

nullable

backup_codes

Backup codes. Only on successful verify action.

Array<string>

Example ^generated

{
  "secret": "example",
  "qr_uri": "example",
  "token": "example",
  "expires_at": "2026-04-15T12:00:00Z",
  "backup_codes": [
    "example"
  ]
}

400

Malformed request or invalid code.

Media type application/json

object

code

required

Machine-readable error code (e.g. “not_found”, “tenant_mismatch”).

string

message

required

Human-readable description of the error.

string

details

Optional additional context about the error.

object

key

additional properties

any

notices

Policy notices from determining Cedar rules, if applicable.

Array<string>

Example ^generated

{
  "code": "example",
  "message": "example",
  "details": {},
  "notices": [
    "example"
  ]
}

401

Challenge not found or expired.

Media type application/json

object

code

required

Machine-readable error code (e.g. “not_found”, “tenant_mismatch”).

string

message

required

Human-readable description of the error.

string

details

Optional additional context about the error.

object

key

additional properties

any

notices

Policy notices from determining Cedar rules, if applicable.

Array<string>

Example ^generated

{
  "code": "example",
  "message": "example",
  "details": {},
  "notices": [
    "example"
  ]
}