Login
POST/api/auth/login
Authenticates a user with email and password.
A login alert will be sent to the user's email if this setting is enabled email is enabled and configured correctly.
If there is an account associated with the given email address but this account did not set up password authentication, an Identity Provider Information email will be sent if email is enabled.
Optional session data:
- The
sessionobject can be included in the request body. - Inside the
sessionobject, 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.
2FA:
If the user enabled 2FA, the user will not be authenticated immediately.
Instead, a TwoFactorAuthenticationToken
is set as HTTP-only cookie and returned in the response body
if header authentication is enabled.
You can complete the login through the endpoint POST /api/auth/2fa/login.
Locale
A locale can be specified for this request. This will be used for the email 2FA code if this method is enabled for the user. You can learn more about 2FA through email here.
If no locale is specified, the applications default locale will be used. You can learn more about configuring the default locale here.
Tokens
- If 2FA is disabled and the request is successful,
AccessTokenandRefreshTokenwill automatically be set as HTTP-only cookies. If header authentication is enabled,AccessTokenandRefreshTokenwill be returned in the response body and can be used as bearer tokens in the authorization header for upcoming requests.
Request
Responses
- 200
- 304
- 401
- 500
Authentication successful. Returns tokens and user details.
The following error codes correspond to this status:
ALREADY_AUTHENTICATED: Principal is already authenticated.
The following error codes correspond to this status:
INVALID_CREDENTIALS: Invalid credentials.
The following error codes correspond to this status:
DATABASE_FAILURE: Exception representing a general failure related to database operations.INVALID_DATABASE_OBJECT: Indicates an invalid document stored in the database.TWO_FACTOR_AUTHENTICATION_TOKEN_ENCODING_FAILURE: Represents an exception that occurs during the encoding process of an two-factor authentication token.TWO_FACTOR_AUTHENTICATION_TOKEN_SECRET_FAILURE: Represents an exception that occurs when there is a failure related to the secret required for creating an two-factor authentication token.INVALID_PRINCIPAL_DOCUMENT: A requested principal document was stored in an invalid format.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.