Menu

Multi-Factor Authentication (MFA) Factors API Routes

Multi-factor authentication (MFA) factors are additional ways to verify a customer's identity during login, in addition to their password. Examples of MFA factors include authenticator apps, SMS messages, and email. These API routes allow customers to manage their MFA factors, such as enabling an authenticator app or generating recovery codes.

POST /auth/mfa/challenges/{id}/verify#

Verify a Multi-Factor Authentication (MFA) Challenge

Verify a multi-factor authentication (MFA) challenge issued during login. On success, this completes the authentication flow and returns a JWT token that can be used to authenticate subsequent requests.

Authentication: none.

Path parameters

idstring
The MFA challenge's ID.

Request body (application/json)

methodstring
The MFA method used to verify the challenge (for example, totp or recovery-code).
codestring
The verification code generated by the chosen MFA method.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

GET /auth/mfa/factors#

List Multifactor Authentication (MFA) Factors

Retrieve the list of multi-factor authentication (MFA) factors registered for the authenticated user, including both pending (not yet verified) and enabled factors.

Authentication: none.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/mfa/factors#

Start Multi-Factor Authentication (MFA) Factor Enrollment

Start the enrollment of a new multi-factor authentication (MFA) factor for the authenticated user. The response contains the factor along with provider-specific setup data (such as a secret and an otpauth_url for TOTP) that can be used to display a QR code. The factor must then be verified via the verify endpoint before it can be used.

Authentication: none.

Request body (application/json)

providerstring
The ID of the MFA provider to enroll the factor with (for example, totp).
labelstringOptional
A human-readable label to identify the factor (for example, the name of the authenticator app or device).
issuerstringOptional
The issuer name shown in authenticator apps for this factor. Defaults to the application name when omitted.
metadataobjectOptional
Additional provider-specific data to associate with the factor.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /auth/mfa/factors/{id}#

Disable a Multi-Factor Authentication (MFA) Factor

Disable a multi-factor authentication (MFA) factor for the authenticated user. Once disabled, the factor can no longer be used to verify MFA challenges. When disabling a recovery-code factor, a valid recovery code must be provided in the request body.

Authentication: none.

Path parameters

idstring
The MFA factor's ID.

Request body (application/json)

methodstringOptional
The MFA method used to authorize disabling the factor (for example, recovery-code).
codestringOptional
The verification code associated with the provided method, used to confirm the disable action.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/mfa/factors/{id}/verify#

Verify and Enable a Multi-Factor Authentication (MFA) Factor

Verify a pending multi-factor authentication (MFA) factor by submitting a code generated from it. A successful verification enables the factor, after which it can be used to verify MFA challenges during login.

Authentication: none.

Path parameters

idstring
The MFA factor's ID.

Request body (application/json)

codestring
The verification code generated by the MFA factor (for example, the current TOTP code from the authenticator app).

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /auth/mfa/recovery-codes#

Generate Multi-Factor Authentication (MFA) Recovery Codes

Generate a new set of single-use recovery codes for the authenticated user. Recovery codes can be used to verify MFA challenges when the user does not have access to their primary MFA factor. Generating new codes replaces any previously issued codes, so they should be stored in a safe place. At least one enabled MFA factor is required to generate recovery codes.

Authentication: none.

Request body (application/json)

countnumberOptional
The number of recovery codes to generate. Must be between 1 and 50. Defaults to the provider's configured value when omitted.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page