User Authentication with Multi-factor Authentication

If you have multi-factor authentication (MFA) enabled for your account, authentication is performed in two steps:

  1. The first request submits user credentials (username and password) to return an mfa_token in the response instead of the usual auth_token and refresh_token.
  2. The second request sends this mfa_token and the generated one-time password (OTP) code to return the auth_token and refresh_token in the response.

For the second request, provide the following fields:

  • mfa_token (String required) - JWT returned from the first request
  • code (String required) - OTP code
  • trusted_device (Object optional) - Device details to determine if the second MFA step is skipped in the future

This data is stored if the second request is successful and includes the trusted_device object with the fingerprint, operating system, and browser.

Providing an MFA code is unnecessary if the device is already trusted. So, if the first request includes a unique identifier (known as a “fingerprint”) for a device that matches the fingerprint of a trusted device for your account, the auth_token and refresh_token are returned immediately. A device remains trusted for 30 days.

MFA Key Object

The following table describes the properties of the MFA key object.

Property Type Description
id Integer Unique identifier of this MFA key
status Object Information about the MFA key status (see Status Object)
type Object Information about the MFA key type (see Type Object)
secret_key String A Base32 encoded secret key for this MFA key
Note: This only displays on creation
otpauth String The secret key, but URI-encoded for QR codes
Note: This only displays on creation
creation_date Timestamp Date/time when this MFA key was created
Type: ISO 8601 timestamp format
activation_date Timestamp Date/time when this MFA key was activated
Type: ISO 8601 timestamp format

Status Object

Property Type Description
id Integer Status ID of this MFA key
description String Description of the status

Type Object

Property Type Description
id Integer Type ID of this MFA key
description String Description of the type

Errors

The following table lists errors that may occur with this call.

HTTP Status Error Code Error Token Description Scenario
401 - - Unauthorized Given password is invalid
409 1405 Duplicated MFA already activated Can’t create a 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 or type is required