User Authentication with Multi-factor Authentication
Warning: To improve security across our services, authentication with user credentials has now been deprecated. Please authenticate with application tokens instead.
See the deprecation notice for more information about why BICS is making this change.
If you have multi-factor authentication (MFA) enabled for your account, authentication is performed in two steps:
- The first request submits user credentials (username and password) to return an
mfa_token
in the response instead of the usualauth_token
andrefresh_token
. - The second request sends this
mfa_token
and the generated one-time password (OTP) code to return theauth_token
andrefresh_token
in the response.
For the second request, provide the following fields:
mfa_token
(String required) - JWT returned from the first requestcode
(String required) - OTP codetrusted_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 |