Two-Factor Authentication (2FA)

🚧

Important

2FA is enabled by default for all users.
If you want to make 2FA optional for your users, contact your Account Manager.

How to enable or disable Two-Factor Authentication

The same process applies for both enabling and disabling.

📘

The users will be able to manage 2FA via their profiles in case 2FA is configured as an optional feature in your settings. If it is configured as mandatory, users will not be able to enable or disable it themselves.

Step 1. Switch the current method

Endpoint

POST /reg/mfa/authorization/switch

Description

Use this endpoint to enable or disable Two-Factor authentication — it sends a confirmation code and returns a 200 OK response if the request is successful.

Step 2. Confirm switching the method

Endpoint

POST /reg/mfa/authorization/switch/confirm

Description

Provide the confirmation code sent by the previous endpoint. If the code is correct, the MFA method is switched, and a 200 OK response is returned.

🚧

Confirmation code requirements

Code format:

• 6-digit numeric code;
• only numbers allowed;

Code expiry:

• valid for 5 minutes;
• expired codes cannot be used for verification;

Resend policy:

• a new code can be requested once every 60 seconds;
• frequent requests are restricted;

Verification attempts & account lock:

• users have 5 attempts to enter the correct code;
• after 5 failed attempts, the account is temporarily locked;
• the account automatically unlocks after a predefined period.

To check whether 2FA is enabled for a user, use the Retrieve User Information endpoint.

Response Example

{
  ...
  "authorizationMfaActive": false
}  

The authorizationMfaActive field returns true if two-factor authentication is enabled, and false if it is disabled.

How to log in with 2FA enabled

If 2FA is activated, the standard authorization process includes an additional step for entering the code.

Step 1. Enter Email and Password

Endpoint

POST /reg/v1/auth/token

Description

This endpoint initiates authentication using email and password. If 2FA is enabled for the account, the system returns a FAILED_DEPENDENCY response and sends a 6-digit verification code to the user's email. The code must be submitted in a subsequent request to complete authentication.

Body Parameters

Headers:

Response Example

  {
  "status": "FAILED_DEPENDENCY",
  "message": "2FA is required for this account",
  "traceId": "TraceId unavailable",
  "errors": []
}

A confirmation code is sent to the user's email.

Step 2. Enter confirmation code

Endpoint

POST /reg/v1/auth/token

Description

Use this endpoint again and include the confirmation code.

Body Parameters

Headers:

Response Example

  {
    "access_token": "string",
    "token_type": "Bearer",
    "refresh_token": "string",
    "scope": "exchange:show payin:show user_mfa:read user_mfa:create deposit_crypto:show withdraw_crypto:show cardholder_user:show bank_account:show",
    "expires_in": 604800,
    "user_id": "usr:97194684-29f8-468f-8a67-249f30240655"
}

As a result, the user receives a new access token.

How to resolve possible errors

Failed 2FA code attempts do not count as failed login attempts.

After successful 2FA code validation, the attempt counter resets, allowing 5 new attempts for subsequent logins.