# MFA ## Recover MFA - [POST /resources/auth/v1/user/mfa/recover](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_recovermfa.md): Recover multi-factor authentication (MFA) for a non-logged-in user. This endpoint verifies a user's identity using a backup recovery code, typically generated by the user's MFA authenticator app during initial setup. Use this when a user cannot access their MFA device and needs to authenticate with their recovery code. ## Disable authenticator app MFA - [POST /resources/users/v1/mfa/authenticator/{deviceId}/disable/verify](https://developers.frontegg.com/ciam/api/identity/mfa/usersmfacontrollerv1_disableauthenticatormfa.md): Disable multi-factor authentication (MFA) enrollment for a logged-in user within a specific account (tenant). This endpoint removes MFA for a user, typically used in administrative contexts where a backend system or admin manages user security settings. The request must include the mfaToken, which is the time-based one-time password (TOTP) generated by the user's authenticator app. Use this endpoint to programmatically disable MFA for a specific user within an account (tenant). ## Pre-disable SMS MFA - [POST /resources/users/v1/mfa/sms/{deviceId}/disable](https://developers.frontegg.com/ciam/api/identity/mfa/usersmfacontrollerv1_predisablesmsmfa.md): Initiate the process of disabling SMS-based multi-factor authentication (MFA) for a specific device. Provide the target deviceId in the request path to mark the SMS MFA device for pre-disablement. This action prepares the device for subsequent steps required to complete the removal. Use this route as part of the MFA management flow for disabling SMS-based MFA on a per-device basis. ## Disable SMS MFA - [POST /resources/users/v1/mfa/sms/{deviceId}/disable/verify](https://developers.frontegg.com/ciam/api/identity/mfa/usersmfacontrollerv1_disablesmsmfa.md): Complete the process of disabling SMS-based multi-factor authentication (MFA) for a specific device. This step finalizes MFA deactivation for the given deviceId after a prior pre-disable action. The request must include: - otcToken: The one-time challenge token obtained during the pre-disable step. - code: The SMS verification code received by the user. Use this endpoint as the second step in the SMS MFA removal flow to verify the user's identity and confirm the disable action. ## Request verify MFA using email code - [POST /resources/auth/v1/user/mfa/emailcode](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_preverifyemailotcmfa.md): Verify multi-factor authentication (MFA) using a code sent to the user's email. This endpoint completes the email-based MFA verification step. The request must include: - mfaToken: The token provided after the user initiates MFA via email. Use this endpoint to confirm the email-based MFA challenge and finalize the login or authentication process. ## Verify MFA using email code - [POST /resources/auth/v1/user/mfa/emailcode/verify](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_verifyemailotcmfa.md): Verify a multi-factor authentication (MFA) challenge using a code sent to the user's email address. This endpoint finalizes the email-based MFA verification and completes the authentication process. The request must include: - otcToken: One-time challenge token received during the email MFA initiation. - code: The MFA code sent to the user's email. - mfaToken: Token returned from the original MFA setup or step-up authentication request. - rememberDevice (optional): If set to true, the device will be remembered to reduce MFA prompts on future logins from the same client. Use this endpoint to confirm the MFA challenge and optionally remember the current device for future sessions. ## Pre enroll MFA using Authenticator App - [POST /resources/auth/v1/user/mfa/authenticator/enroll](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_preenrollauthenticatormfa.md): Initiate enrollment in multi-factor authentication (MFA) using an authenticator app (e.g., Google Authenticator, Authy). This endpoint begins the MFA setup process and returns the necessary data for configuring an authenticator app, such as a QR code or secret key. The request must include: - mfaToken: A token received from the initial authentication flow that authorizes the MFA setup. Use this endpoint to generate the configuration required for linking an authenticator app before completing verification. ## Enroll MFA using Authenticator App - [POST /resources/auth/v1/user/mfa/authenticator/enroll/verify](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_enrollauthenticatormfa.md): Complete enrollment in multi-factor authentication (MFA) using an authenticator app. This endpoint verifies the MFA setup by validating the time-based one-time password (TOTP) generated by the authenticator app. The request must include: - token: The 6-digit TOTP code generated by the authenticator app. - mfaToken: Token from the initial MFA enrollment initiation. - rememberDevice (optional): If set to true, the device will be remembered and may skip MFA on future logins from the same browser or device. Use this endpoint to finalize MFA enrollment and activate the authenticator app for the user's account. ## Verify MFA using authenticator app - [POST /resources/auth/v1/user/mfa/authenticator/{deviceId}/verify](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_verifyauthenticatormfa.md): Verify multi-factor authentication (MFA) during the authentication process. This endpoint is typically used after a primary login attempt when MFA is enabled for the user or account (tenant). The request must include: - value: The MFA service name (e.g., authenticator, email, sms) configured under Authentication Settings. - mfaToken: The token or code provided by the user's MFA method (e.g., code from an authenticator app). Use this endpoint to complete the MFA verification step as part of the overall login flow. ## Pre-enroll MFA using sms - [POST /resources/auth/v1/user/mfa/sms/enroll](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_preenrollsmsmfa.md): Initiate multi-factor authentication (MFA) enrollment using SMS. This endpoint begins the SMS-based MFA setup by sending a verification code to the provided phone number. The request must include: - phoneNumber: The user's mobile phone number in international format. It must match the format defined in your organization's phone number validation pattern (phoneNumberRegexp). Use this endpoint as the first step in enabling SMS-based MFA for a user. ## Enroll MFA using sms - [POST /resources/auth/v1/user/mfa/sms/enroll/verify](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_enrollsmsmfa.md): Complete enrollment in multi-factor authentication (MFA) using SMS. This endpoint finalizes the SMS-based MFA setup for the user by verifying the code sent to their phone number. The request must include: - otcToken: Token received from the initial SMS MFA enrollment step. - code: The numeric code sent via SMS to the user's registered phone number. Use this endpoint to verify the user's phone number and activate SMS-based MFA on their account. ## Request to verify MFA using sms - [POST /resources/auth/v1/user/mfa/sms/{deviceId}](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_preverifysmsmfa.md): Verify multi-factor authentication (MFA) using an SMS-based device. This endpoint confirms the SMS MFA challenge as part of the authentication or step-up verification process for a specific registered device. Path parameters: - deviceId: The unique identifier of the SMS MFA device being verified. Request body must include: - mfaToken: Token provided during the authentication or challenge flow. Use this endpoint to complete SMS-based MFA verification for the specified device. ## Verify MFA using sms - [POST /resources/auth/v1/user/mfa/sms/{deviceId}/verify](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_verifysmsmfa.md): Verify a multi-factor authentication (MFA) challenge using an SMS code for a specific registered device. This endpoint finalizes the MFA step by validating the SMS code and may mark the device as trusted if specified. Path parameters: - deviceId: The unique identifier of the SMS MFA device being verified. Request body must include: - otcToken: Token received from the SMS MFA challenge initiation. - code: The verification code sent to the user's phone via SMS. - mfaToken: MFA token issued during the initial login or step-up challenge. - rememberDevice (optional): Set to true to remember the device and reduce future MFA prompts on this device. Use this endpoint to complete SMS-based MFA verification and optionally trust the device for future logins. ## Pre enroll MFA using WebAuthN - [POST /resources/auth/v1/user/mfa/webauthn/enroll](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_preenrollwebauthnmfa.md): Initiate multi-factor authentication (MFA) enrollment using WebAuthn (e.g., security keys, biometrics). This endpoint begins the WebAuthn MFA setup by returning a browser-based challenge needed to link a trusted device, such as a biometric reader or hardware security key. The request must include: - mfaToken: Token issued during the authentication flow to authorize MFA setup. Use this endpoint as the first step when enrolling a user in WebAuthn-based MFA. ## Enroll MFA using WebAuthN - [POST /resources/auth/v1/user/mfa/webauthn/enroll/verify](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_enrollwebauthnmfa.md): Complete enrollment in multi-factor authentication (MFA) using WebAuthn. This endpoint verifies and registers a WebAuthn device, such as a biometric sensor (Platform) or hardware security key (CrossPlatform), finalizing the setup after the initial challenge. The request must include: - deviceType: Type of device being enrolled. Accepts Platform (e.g., fingerprint scanner) or CrossPlatform (e.g., USB security key). - webauthnToken: Token received during the WebAuthn pre-enrollment step. - options: WebAuthn attestation data collected from the client. - id: Device identifier. - response: WebAuthn attestation response. - clientDataJSON: Base64-encoded client data from the browser. - attestationObject: Base64-encoded attestation object from the authenticator. - deviceType (optional): May repeat the selected device type. - mfaToken: Token used to authorize MFA enrollment. - rememberDevice (optional): Set to true to remember the device and reduce MFA prompts on future logins. Use this endpoint to complete WebAuthn-based MFA enrollment and register the user's trusted device. ## Request verify MFA using WebAuthN - [POST /resources/auth/v1/user/mfa/webauthn/{deviceId}](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_preverifywebauthnmfa.md): Verify a multi-factor authentication (MFA) challenge using a registered WebAuthn device. This endpoint completes WebAuthn-based MFA verification, typically following primary authentication when WebAuthn is required as a second factor. Path parameters: - deviceId: The unique identifier of the WebAuthn device to be verified. Request body must include: - mfaToken: Token issued during the login or step-up authentication flow. Use this endpoint to validate a WebAuthn device and complete the MFA step during authentication. ## Verify MFA using webauthn - [POST /resources/auth/v1/user/mfa/webauthn/{deviceId}/verify](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_verifywebauthnmfa.md): Verify a multi-factor authentication (MFA) challenge using a WebAuthn device. This endpoint completes MFA verification using a previously registered WebAuthn device such as a biometric sensor or hardware security key. Path parameters: - deviceId: The unique identifier of the registered WebAuthn device to be verified. Request body must include: - webauthnToken: Token received from the server to initiate the WebAuthn challenge. - options: WebAuthn authentication response returned by the browser. - id: The credential ID of the WebAuthn device. - response: Object containing attestation data from the authenticator. - clientDataJSON: Base64-encoded client data. - authenticatorData: Base64-encoded data from the authenticator. - signature: Signature from the authenticator, proving user presence. - userHandle: The user's handle used during registration. - recaptchaToken (optional): Token to verify human interaction, if reCAPTCHA is enabled. - invitationToken (optional): Used when completing an MFA challenge as part of an invitation flow. - mfaToken: Token issued during the initial authentication step. - rememberDevice (optional): If set to true, this device will be remembered for future logins to reduce MFA prompts. Use this endpoint to complete WebAuthn-based MFA verification and confirm the user's identity using a secure hardware or platform authenticator. ## Check if remember device allowed - [GET /resources/configurations/v1/mfa-policy/allow-remember-device](https://developers.frontegg.com/ciam/api/identity/mfa/securitypolicycontroller_checkifallowtorememberdevice.md): Check whether the 'remember device' feature is allowed for MFA verification. This endpoint returns whether device remembering is enabled globally or for a specific account (tenant), based on the request context. Query parameters: - mfaToken: Token generated from the authenticator app or MFA challenge step. Use this endpoint to determine whether the user should be prompted with the option to remember their device during MFA verification. ## Enroll authenticator app MFA - [POST /resources/users/v1/mfa/authenticator/enroll](https://developers.frontegg.com/ciam/api/identity/mfa/usersmfacontrollerv1_enrollauthenticatormfa.md): Enroll a logged-in user in multi-factor authentication (MFA) for a specific account (tenant). This endpoint initiates MFA enrollment on behalf of a user within a specific account (tenant) context. Use this route to programmatically trigger MFA enrollment, typically as part of an administrative or backend workflow. ## Verify authenticator app MFA enrollment - [POST /resources/users/v1/mfa/authenticator/enroll/verify](https://developers.frontegg.com/ciam/api/identity/mfa/usersmfacontrollerv1_verifyauthenticatormfaenrollment.md): Verify multi-factor authentication (MFA) enrollment using a QR code for a specific user within an account (tenant). This endpoint completes MFA enrollment after the user scans a QR code with an authenticator app (e.g., Google Authenticator, Authy). Request body must include: - mfaToken: The time-based one-time password (TOTP) generated by the authenticator app after scanning the QR code. Use this endpoint to confirm that the user has successfully registered their authenticator app and to activate MFA for their account. ## Enroll SMS MFA - [POST /resources/users/v1/mfa/sms/enroll](https://developers.frontegg.com/ciam/api/identity/mfa/usersmfacontrollerv1_preenrollsmsmfa.md): Enroll a user in SMS-based multi-factor authentication (MFA). This endpoint initiates SMS MFA enrollment by sending a verification code to the user's phone number. Request body must include: - phoneNumber: The user's mobile number in international format. Must match the validation pattern defined by phoneNumberRegexp. Use this endpoint to begin the SMS MFA setup process for a specific user. The next step is to verify the SMS code to complete enrollment. ## Verify MFA enrollment - [POST /resources/users/v1/mfa/sms/enroll/verify](https://developers.frontegg.com/ciam/api/identity/mfa/usersmfacontrollerv1_enrollsmsmfa.md): Complete SMS-based multi-factor authentication (MFA) enrollment for a user. This endpoint finalizes SMS MFA setup by verifying the code sent to the user's phone. Request body must include: - otcToken: One-time challenge token received from the initial enrollment step. - code: The verification code sent to the user's phone via SMS. Use this endpoint to verify the user's phone number and activate SMS-based MFA for their account. ## Disable authenticator app MFA (deprecated) - [POST /resources/users/v1/mfa/disable](https://developers.frontegg.com/ciam/api/identity/mfa/usersmfacontrollerv1_disableauthappmfa.md): Disable MFA enrollment for a logged-in user within a specific account (tenant). This endpoint disables multi-factor authentication for a user, using the mfaToken obtained from the user's authenticator app. Use this endpoint to programmatically disable MFA when managing authentication settings at the account (tenant) level. ## Verify MFA using code from authenticator app (deprecated) - [POST /resources/auth/v1/user/mfa/verify](https://developers.frontegg.com/ciam/api/identity/mfa/authenticationmfacontrollerv1_verifyauthenticatormfacode.md): Verify a multi-factor authentication (MFA) code generated by an authenticator app during the authentication process. This endpoint completes the MFA step by validating the provided code. The request must include: - value: The MFA service name (e.g., authenticator), as configured in your Authentication Settings. - mfaToken: The time-based one-time password (TOTP) generated by the user's authenticator app. Use this endpoint to verify the user's MFA code during an authentication challenge, typically after the primary login step. ## Enroll authenticator app MFA (deprecated) - [POST /resources/users/v1/mfa/enroll](https://developers.frontegg.com/ciam/api/identity/mfa/usersmfacontrollerv1_enrollauthappmfa.md): Enroll a logged-in user in multi-factor authentication (MFA) for a specific account (tenant). This endpoint initiates MFA enrollment on behalf of a user within a specific account (tenant) context. Use this route to programmatically trigger MFA enrollment, typically as part of an administrative or backend workflow. ## Verify authenticator app MFA enrollment (deprecated) - [POST /resources/users/v1/mfa/enroll/verify](https://developers.frontegg.com/ciam/api/identity/mfa/usersmfacontrollerv1_verifyauthappmfaenrollment.md): Verify multi-factor authentication (MFA) enrollment using a QR code for a specific user. This endpoint completes MFA setup after the user scans a QR code with their authenticator app (e.g., Google Authenticator, Authy). Request body must include: - mfaToken: The time-based one-time password (TOTP) generated by the user's authenticator app after scanning the QR code. Use this endpoint to confirm that the user has successfully linked their authenticator app and to activate MFA for their account.