User Authentication with Multi-factor Authentication

If a user has multi-factor authentication enabled for his account, Authentication is performed in 2 steps:

  1. The initial submission of the credentials (username/password) gets an mfa_token in the response instead of auth_token and refresh_token.
  2. The second “authenticate” request with this mfa_token and the generated OTP code for the multi-factor authentication will then receive the auth_token and refresh_token in the response. The following fields are provided for this step:
  • mfa_token (String required) - JWT returned from the 1st step
  • code (String required) - “One-Time Password” code
  • trusted_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 and refresh_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

Auth Sequence

MFA Sequence