Home B2Core API Authenticate a client and obtain the access token

Authenticate a client and obtain the access token

This tutorial provides detailed instructions on authenticating a previously registered client and obtaining a pair of access and refresh tokens. The access token must be included as the Bearer Authorization Header when using any other B2Core API methods.

To authenticate a client, follow the steps below:

  1. To start an authentication procedure, initialize the Sign In wizard:

GET[host]/api/v2/my/signin/wizard

  1. Enter client credentials:

POST[host]/api/v2/my/signin

  1. If both methods of two-factor authentication (2FA), the Google Authenticator app and SMS codes, are enabled for the client, select the preferred 2FA method:

POST[host]/api/v2/my/signin/2fa

If only one 2FA method is enabled for the client, skip this step and proceed to Step 4.

  1. Complete authentication by submitting a 2FA code from the enabled 2FA method:

POST[host]/api/v2/my/2fa/google – to submit a code from the Google Authenticator app

or

POST[host]/api/v2/my/2fa/sms – to submit a code sent to the client phone number via SMS

Step 1

Initialize the Sign In wizard:

Request

Header parameters:

  • Accept: application/json

  • Content-Type: application/json

GET[host]/api/v2/my/signin/wizard

curl --location --request GET 'https://host.name/api/v2/my/signin/wizard' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Response

code integer

An HTTP code specifying the current step of an authentication procedure:

  • HTTP code 200 for an intermediary step after which another page of an authentication form is displayed to a client

  • HTTP code 202 for a final wizard step signaling that client authentication succeeded

data object or null

The object that includes the following fields:

Show object fields
recaptcha object

The details about reCAPTCHA:

Show object fields
enabled boolean

If true, reCAPTCHA is added to the Sign In page; otherwise, false.

is_qr_available boolean

If true, a QR code is displayed on the Sign In page, enabling a client to sign in by scanning the QR code; otherwise, false.

is_password_recovery_available boolean

If true, a client can restore a forgotten password by clicking a password recovery link displayed on the Sign In page; otherwise, false.

done boolean

If true, a client was successfully authenticated; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to an authentication procedure.

workflow string

The string value login indicates that client credentials must be entered at the next step.

RESPONSE EXAMPLE — STEP 1 
{
  "code": 200,
  "data": {
    "recaptcha": {
      "enabled": false
      },
    "is_qr_available": true,
    "is_password_recovery_available": true
    },
  "done": false,
  "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
  "workflow": "login"
}

Step 2

Enter client credentials.

Note

If you exceed the allowed number of sign-in attempts, you won’t be allowed to authenticate during a certain period.

The default number of allowed attempts is 5 within a minute, and the default blocking period is 10 minutes.

The default limits can be changed by the admin in the section User Auth Settings, which is available upon navigating to System > Settings in the Back Office.

Request

Header parameters:

  • Accept: application/json

  • Content-Type: application/json

Body:

uuid string required

The universally unique identifier (UUID) assigned to an authentication procedure.

email string required

The client email address.

password string required

The client password.

device_fingerprint string required

The free-form JSON data (which includes the required user_agent field) generated by a client in the format of a Base64-encoded string that uniquely identifies a device from which a request is sent.

To learn how to get a device fingerprint, refer to Obtain a device fingerprint.

recaptchaResponse string

The reCAPTCHA response token.

POST[host]/api/v2/my/signin

curl --location --request POST 'https://host.name/api/v2/my/signin' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "uuid": "03b612d1-e973-4f1e-bf8f-d97f88515104",
  "email": "username@example.com",
  "password": "QAzqw123!",
  "device_fingerprint": "eyJ1c2VyX2FnZW50IjoiTW96aWxsYVwvNS4wIChXaW5kb3dzIE5UIDEwLjA7IFdpbjY0OyB4NjQpIEFwcGxlV2ViS2l0XC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWVcLzExOC4wLjAuMCBTYWZhcmlcLzUzNy4zNiJ9"
}'

Response

code integer

An HTTP code specifying the current step of an authentication procedure:

  • HTTP code 200 for an intermediary step after which another page of an authentication form is displayed to a client

  • HTTP code 202 for a final wizard step signaling that client authentication succeeded

data object or null

If authentication has succeeded, the details about the access and refresh tokens:

Show object fields
token string

The access or refresh token.

createdAt string

The date and time when a token was generated.

expiresAt string

The date and time when a token is due to expire.

tfaProviders array

The details about 2FA methods:

Show object fields
name string

The 2FA method name. Possible value:

  • google — the Google Authenticator app

  • sms — SMS codes

localizedCaption string

The localized name of a 2FA method, displayed to a client.

enabled boolean

If true, a 2FA method is enabled; otherwise, false.

done boolean

If true, a client was successfully authenticated; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to an authentication procedure.

workflow string

A string value indicating the final or next step of an authentication procedure. Possible values:

  • Terminate — indicates that authentication succeeded and the access and refresh tokens were obtained.

  • 2fa_google_auth — indicates that authentication must be completed by providing a 2FA code from the Google Authenticator app. Next, proceed to Step 4 and use POST[host]/api/v2/my/2fa/google.

  • 2fa_sms_auth — indicates that authentication must be completed by providing a 2FA code sent to a client phone number. Next, proceed to Step 4 and use POST[host]/api/v2/my/2fa/sms.

  • 2fa — indicates that both 2FA methods are enabled for a client (the Google Authenticator app and SMS codes). Next, proceed to Step 3 and select the preferred 2FA method.

RESPONSE EXAMPLE — STEP 3 
{
  "code": 200,
  "data": {
     "accessToken": null,
     "refreshToken": null,
     "tfaProviders": []
  },
  "done": false,
  "uuid": "03b612d1-e973-4f1e-bf8f-d97f88515104",
  "workflow": "2fa"
}

Step 3

Select the preferred 2FA method.

Request

Body:

Header parameters:

  • Accept: application/json

  • Content-Type: application/json

uuid string required

The universally unique identifier (UUID) assigned to an authentication procedure.

type string required

Specify the 2FA method to be used to complete authentication. Possible values:

  • google — to use a code from the Google Authenticator app

  • sms — to use a code sent to a client phone number via SMS

POST[host]/api/v2/my/signin/2fa

curl --location --request POST 'https://host.name/api/v2/my/signin/2fa' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
  "type": "google"
}'

Response

code integer

An HTTP code specifying the current step of an authentication process:

  • HTTP code 200 for an intermediary step after which another page of an authentication form is displayed to a client

  • HTTP code 202 for a final wizard step signaling that client authentication succeeded

data object

Always null.

done boolean

If true, a client was successfully authenticated; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to an authentication procedure.

workflow string

A string value indicating the next step of an authentication procedure. Possible values:

  • 2fa_google_auth — indicates that authentication must be completed by providing a 2FA code from the Google Authenticator app. Next, proceed to Step 4 and use POST[host]/api/v2/my/2fa/google.

  • 2fa_sms_auth — indicates that authentication must be completed by providing a 2FA code sent to a client phone number. Next, proceed to Step 4 and use POST[host]/api/v2/my/2fa/sms.

RESPONSE EXAMPLE - STEP 3 
{
  "code": 200,
  "data": null,
  "done": false,
  "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
  "workflow": "2fa_google_auth"
}

Step 4

Complete authentication by submitting a code from the enabled 2FA method.

In this example, the method for submitting a 2FA code from the Google Authenticator app is demonstrated. To submit a code sent to a client phone number via SMS, use the method POST[host]/api/v2/my/2fa/sms.

Request

Body:

uuid string required

The universally unique identifier (UUID) assigned to an authentication procedure.

code string required

A code from the Google Authenticator app.

POST[host]/api/v2/my/2fa/google

curl --location --request POST 'https://host.name/api/v2/my/2fa/google' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
  "code": "678562"
}'

Response

code integer

An HTTP code specifying the current step of an authentication procedure:

  • HTTP code 200 for an intermediary step after which another page of an authentication form is displayed to a user

  • HTTP code 202 for a final wizard step signaling that client authentication succeeded

data object or null

The access token and refresh token data:

Show object fields
token string

The access or refresh token.

createdAt string

The date and time when a token was generated.

expiresAt string

The date and time when a token is due to expire.

done boolean

If true, a client was successfully authenticated; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to an authentication procedure.

workflow string

The string value Terminate indicates that a client was successfully authenticated and the access and refresh tokens were obtained.

RESPONSE EXAMPLE — STEP 4 
{
    "code": 202,
    "data": {
        "accessToken": {
            "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3MTM3ODQwNDQsIm5iZiI6MTcxMzc4NDA0NCwiZXhwIjoxNzEzNzg0OTQ0LCJpc3MiOiJodHRwczovL3N0YW5kLXFhLTA0LWFwaS5iMmJyb2tlci50ZWNoIiwic3ViIjoiODciLCJpYXRfbXQiOiIxNzEzNzg0MDQ0LjY2NzYifQ.XKK0j6H9879rvGo0a5w5OekQBhq1FsiLEx-4ZVWeS-CStccmJDwvyW_Q36K31rRBIZdBhE2U37MN9NAAb1qofCmFwysqNH-OUaKU-3N4eg7RyMsAI0jXCLF_X2miEdX1XteKO9kfTz_ASblPhSBn0F1jhlpow7wpQKet_M",
            "createdAt": "2024-04-22T11:07:24+00:00",
            "expiresAt": "2024-04-22T11:22:24+00:00"
        },
        "refreshToken": {
            "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3MTM3ODQwNDQsIm5iZiI6MTcxMzc4NDA0NCwiZXhwIjoxNzEzNzg3NjQ0LCJpc3MiOiJodHRwczovL3N0YW5kLXFhLTA0LWFwaS5iMmJyb2tlci50ZWNoIiwic3ViIjoiODciLCJpYXRfbXQiOiIxNzEzNzg0MDQ0LjY3MjMifQ.Aq0VIz2_kXbQwmBmZ0-sKk8MlU8yzBcxWqEUg2DmfG84Omz4AxpAnGoLNpVPh7dP6cFwoHhenXdnvaFgK2ob2_MYWpAk_grWK-vv4FIlYA1mywyvbmjEqRWRfWDwea24GevBLV95YZRdkEBslUkzASdfioiVTuR7zsdtXms",
            "createdAt": "2024-04-22T11:07:24+00:00",
            "expiresAt": "2024-04-22T12:07:24+00:00"
        },
        "tfaProviders": []
    },
    "done": true,
    "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
    "workflow": "Terminate"
}