Manage MFA via API

MFA uses two Access Manager APIs:

Identity enrolls methods and manages the user’s MFA settings.
Auth completes the second verification step during sign-in.

Read Multi-factor authentication before you integrate these operations.

Account enrollment operations

The Identity API exposes these self-service operations:

Operation	Purpose
`POST /v1/users/{id}/mfa/setup`	Start setup for `app` or `email`.
`POST /v1/users/{id}/mfa/verify`	Verify the setup passcode.
`POST /v1/users/{id}/mfa/enable`	Enable the verified method.
`GET /v1/users/{id}/mfa`	Read the current MFA status and enabled methods.
`PATCH /v1/users/{id}/mfa/preferred`	Select the preferred enabled method.
`DELETE /v1/users/{id}/mfa`	Disable all methods.

The standard operations are self-service. The bearer-token subject must match {id}.

Start setup

Send the method in the request body:

Request

{
  "mfaType": "app"
}

This feature supports app and email. Authenticator-app setup returns a secret, a QR-code URL, and recovery codes. Email setup returns recovery codes and sends a passcode to the user’s saved email address.

Verify setup

Submit the 6–8-character setup passcode and the method. Authenticator-app verification also needs the secret returned by setup.

Request

{
  "mfaType": "app",
  "passcode": "123456",
  "secret": "setup-secret"
}

Enable the method

After verification, enable the method with one recovery code from the setup response. Authenticator-app enablement also needs the setup secret.

Request

{
  "mfaType": "app",
  "secret": "setup-secret",
  "recoveryCode": "recovery-code"
}

Treat setup secrets and recovery codes as credentials. Do not log them or store them in source control.

The first factor uses Request Access Token. When MFA is required, the operation returns an MFA challenge response instead of access tokens. The response includes:

mfaRequired: true.
a short-lived mfaToken.
the enabled methods.
the preferred method.

Request email delivery

Use Initiate MFA Challenge for email.

Request

{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "email"
}

Do not request delivery for app. The authenticator app generates the passcode locally.

Verify the second factor

Use Verify MFA Login. Send either passcode or recoveryCode, not both.

Passcode

{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "app",
  "passcode": "123456"
}

Recovery code

{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "app",
  "recoveryCode": "unused-recovery-code"
}

A successful verification returns the standard access-token response. A recovery code is consumed after one successful use.

Error handling

Important login errors include:

Code	Meaning
`AUT-0015`	MFA is required before Auth can issue access tokens.
`AUT-0016`	The passcode or recovery code is invalid.
`AUT-0017`	The MFA session expired. Restart sign-in.
`AUT-0018`	The verification or resend limit was exceeded.
`AUT-0019`	The selected method still needs setup.
`AUT-0020`	The MFA token is invalid.

Identity can also reject an unsupported method, missing setup secret, missing email destination, or unverified setup. See the Access Manager error list for the full error envelope and current codes.

Complete MFA in the Console

The user workflow for verification during sign-in.

Identity APIs

The generated reference for account-management operations.

Getting started

Features

Deployment and operations

Architecture

Identity provider (Caradhras)

Manage MFA via API

Account enrollment operations

Start setup

Verify setup

Enable the method

Request email delivery

Verify the second factor

Error handling

Complete MFA in the Console

Identity APIs

​Account enrollment operations

​Start setup

​Verify setup

​Enable the method

​Login operations

​Request email delivery

​Verify the second factor

​Error handling

​Related pages

Complete MFA in the Console

Identity APIs

Account enrollment operations

Start setup

Verify setup

Enable the method

Login operations

Request email delivery

Verify the second factor

Error handling

Related pages