Two-Factor Authentication (2FA)

Two-Factor Authentication (2FA) is an additional security layer for account access. After entering email and password, users must verify their identity using a six-digit code sent to the email. This feature ensures compliance with security standards and protects users' data.

You can enforce mandatory 2FA for all new and existing users by enabling registration.partner.mandatory_mfa parameter.

How to enable or disable Two-Factor authentication

The same process applies for both enabling and disabling.

Endpoint to switch the current method:

POST /reg/mfa/authorization/switch

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.

The users can also manage 2FA themselves via their profiles. A confirmation code sent to the email will be required.

Endpoint to confirm switching the method:

POST /reg/mfa/authorization/switch/confirm

A valid confirmation code sent via previous endpoint must be provided. 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 find out if the 2FA is enabled you can use 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 active, the standard authorization process includes an additional step for entering the code.

Step 1. Enter Email and Password

Endpoint:

POST /reg/v1/auth/token

Use this endpoint to verify if 2FA is enabled and confirmation code must be put in.

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 user's email.

Step 2. Enter confirmation code

Endpoint:

POST /reg/v1/auth/token

Use this endpoint again and enter 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.