Complete Login

POST 
/api/auth/2fa/login

Complete second factor for login.

You can learn more about the login flow here.

Requirements

• User authenticated using their password through POST /api/auth/login.
• At least one of email or TOTP as 2FA methods should be enabled.
• An email or totp 2FA code is present for an enabled 2FA method. Check out email and TOTP to learn how to retrieve a 2FA code.

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").

This information helps users identify and manage authorized sessions, improving overall account security.

Tokens

• A valid TwoFactorAuthenticationToken is required. This token will be set automatically as HTTP-only cookie through POST /api/auth/login or can be retrieved from the response and set as header manually if header authentication is enabled.
• If this action is successful, AccessToken and RefreshToken will automatically be set as HTTP-only cookies. If header authentication is enabled, AccessToken and RefreshToken will be returned in the response body and can be used as bearer tokens in the authorization header for upcoming requests.

Request

Responses

200

Information about the user and the tokens if header authentication is enabled.

304

The following error codes correspond to this status:

• ALREADY_AUTHENTICATED: Principal is already authenticated.

400

The following error codes correspond to this status:

• NO_2FA_CODE_PROVIDED: Invalid request: at least one of email or totp must be provided.
• NO_PASSWORD_PROVIDER: The user needs to set a password in to perform this action.
• 2FA_DISABLED: User needs to set up two-factor authentication to complete 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.
• TWO_FACTOR_CODE_EXPIRED: Two-factor code has expired.
• WRONG_TWO_FACTOR_CODE: Wrong two-factor code.

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.
• 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.
• TOTP_CODE_VALIDATION_FAILURE: Failed to validate TOTP code.
• 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.
• COOKIE_CREATION_FAILURE: Thrown when an exception occurred during the creation of a cookie.
• INVALID_PRINCIPAL_DOCUMENT: A requested principal document was stored in an invalid format.