User Authentication with Multi-factor Authentication
If a user has multi-factor authentication enabled for his account, Authentication is performed in 2 steps:
- The initial submission of the credentials (username/password) gets an
mfa_token
in the response instead ofauth_token
andrefresh_token
. - The second “authenticate” request with this
mfa_token
and the generated OTP code for the multi-factor authentication will then receive theauth_token
andrefresh_token
in the response. The following fields are provided for this step:
mfa_token
(String required) - JWT returned from the 1st stepcode
(String required) - “One-Time Password” codetrusted_device
(Object optional) - details of a “trusted_device” for which the second MFA step will be skipped in the future
- If the “fingerprint” of a trusted device is included in the first authentication request and it matches the “fingerprint” of a device trusted for this user, the
auth_token
andrefresh_token
are returned at once; if this device is already trusted, no MFA code needs to be provided in a second step.- If the second authentication request is successful and includes the details of a “trusted_device” (fingerprint, operating system and browser), then these data will be stored and the “fingerprint” may be used later to authenticate in one step, as just explained in the previous note.
MFA Key Object
Here is the description of the MFA key object
Name | Type | Description |
---|---|---|
id | Integer | Unique ID of this MFA key |
status | Object | ID (Integer) - Id of status of this MFA key description (String) - description of the status |
type | Object | ID (Integer) - Id of type of this MFA key description (String) - description of the type |
secret_key | String | Secret key (encoded in Base32) for this MFA key, will be displayed only on creation |
otpauth | String | Secret key as a URI encoded for QR codes, will be displayed only on creation |
creation_date | Timestamp | Timestamp when this MFA key was created - type: ISO 8601 timestamp format |
activation_date | Timestamp | Timestamp when this MFA key was activated - type: ISO 8601 timestamp format |
Errors
The following table lists errors that may occur as a result of this call
HTTP Status | Error Code | Error Token | Description and parameters | Scenario |
---|---|---|---|---|
401 | - | - | Unauthorized : the given password was invalid | |
409 | 1405 | Duplicated | MFA already activated | Cannot create new MFA key if there is already one active. |
422 | 1400 | InputValidationFailed | InvalidValue | MFA key - Type is invalid |
422 | 1400 | InputValidationFailed | Required | MFA key - password is required / type is required |