Recover From TOTP

POST 
/api/auth/2fa/totp/recover

Recover the user if they lost access to their 2FA device using a recovery code. Each code is only valid once.

You can learn more about recovery for TOTP here.

Requirements

• The user can authenticate using password.
• The user enabled TOTP as 2FA method.

Optional session data:

• The session object can be included in the request body.
• Inside the session object, you can provide the following optional fields:
  • browser: The name of the browser used (e.g., "Chrome", "Firefox").
  • os: The operating system of the device (e.g., "Windows", "macOS", "Android").

Tokens

• A valid TwoFactorAuthenticationToken is required. This token will be set automatically as HTTP-only cookie through POST /api/auth/login or POST /api/auth/step-up or can be retrieved from any of those endpoints' response and set as header manually if header authentication is enabled.

• If this action is successful, AccessToken, RefreshToken and StepUpToken will automatically be set as HTTP-only cookies.

  If header authentication is enabled, AccessToken, RefreshToken and StepUpToken will be returned in the response body and can be used in the authorization header for upcoming requests.

Request

Responses

200

Recovery successful. If header authentication is enabled, the response will contain all tokens.

400

The following error codes correspond to this status:

• TWO_FACTOR_METHOD_DISABLED: Two-factor authentication method is disabled.
• NO_PASSWORD_PROVIDER: The user needs to set a password in to perform this action.

401

The following error codes correspond to this status:

• TWO_FACTOR_AUTHENTICATION_TOKEN_EXPIRED: Indicates that the two-factor authentication token is expired.
• TWO_FACTOR_AUTHENTICATION_TOKEN_INVALID: Indicates that the two-factor authentication token cannot be decoded.
• TWO_FACTOR_AUTHENTICATION_TOKEN_MISSING: Thrown when the two-factor authentication token is missing.
• WRONG_TOTP_RECOVERY_CODE: The given recovery code is not correct.

403

The following error codes correspond to this status:

• STEP_UP_TOKEN_CREATION_FORBIDDEN: Thrown when a step-up token is requested from an illegal context.

404

The following error codes correspond to this status:

• USER_NOT_FOUND: User not found.

500

The following error codes correspond to this status:

• DATABASE_FAILURE: Exception representing a general failure related to database operations.
• HASH_FAILURE: Exception representing a general failure related to hashing operations.
• INVALID_USER_DOCUMENT: A requested user document was stored in an invalid format.
• POST_COMMIT_SIDE_EFFECT_FAILURE: Exception representing a failure to perform a side effect after a successful database operation.
• COOKIE_CREATION_FAILURE: Thrown when an exception occurred during the creation of a cookie.
• ACCESS_TOKEN_CACHE_FAILURE: Thrown when an access token could not be created due to an exception in the access token whitelist.
• ACCESS_TOKEN_ENCODING_FAILURE: Represents an exception that occurs during the encoding process of an access token.
• ACCESS_TOKEN_CREATION_FAILURE: Thrown when a generic exception occurred during the creation of an access token.
• ACCESS_TOKEN_INVALID_PRINCIPAL_DOCUMENT_FAILURE: Indicates that the principal document associated with the access token is invalid.
• ACCESS_TOKEN_SECRET_FAILURE: Represents an exception that occurs when there is a failure related to the secret required for creating an access token.
• REFRESH_TOKEN_ENCODING_FAILURE: Represents an exception that occurs during the encoding process of a refresh token.
• REFRESH_TOKEN_CREATION_FAILURE: Thrown when a generic exception occurred during the creation of an access token.
• REFRESH_TOKEN_INVALID_PRINCIPAL_DOCUMENT_FAILURE: Indicates that the principal document associated with the access token is invalid.
• REFRESH_TOKEN_SECRET_FAILURE: Represents an exception that occurs when there is a failure related to the secret required for creating a refresh token.
• REFRESH_TOKEN_SESSION_UPDATE_FAILURE: Thrown when an exception occurs when updating the user sessions after creating a new refresh token.
• STEP_UP_TOKEN_ENCODING_FAILURE: Represents an exception that occurs during the encoding process of a step-up token.
• STEP_UP_TOKEN_SECRET_FAILURE: Represents an exception that occurs when there is a failure related to the secret required for creating a refresh token.
• INVALID_PRINCIPAL_DOCUMENT: A requested principal document was stored in an invalid format.