Home B2Core API REST API The Front Office API Authentication

Authentication

Use these methods to sign in and out of the B2Core UI.

To allow a client to sign in to the B2Core UI, you need to select which fields are displayed to the client on the login form. To do this, initialize the Sign In Wizard and configure the custom form validation rules.

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

Initialize the Sign In Wizard

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

Sign in to the B2Core UI

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

Refresh the access token

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

Sign out of the B2Core UI

After a client is requested to reset their password by the Back Office admin, use these methods to reset the client password from the Sign In page of the B2Core UI.

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

Reset a password from the Sign In page

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

Set up a new password from the Sign In page

Use these methods to enable clients to sign in to the B2Core UI by scanning QR codes displayed on the Sign In page using the mobile app to which they have already been signed in.

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

Get a QR code sign-in channel

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

Get an authorization token for signing in using a QR code

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

Sign in using a QR code

Initialize the Sign In Wizard

Use this method to initialize the Sign In Wizard for a client and specify the fields displayed on the Sign In page in the B2Core UI.

Request

No parameters.

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

curl --location --request GET 'https://host.name/api/v2/my/signin/wizard' \

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 to the B2Core UI 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, the wizard initialization succeeded; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a client authentication session.

workflow string

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

RESPONSE EXAMPLE 
{
  "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"
}

Sign in to the B2Core UI

Use this method to sign in to the B2Core UI.

Note

If you exceed the allowed number of sign-in attempts, you’ll not 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

Body:

uuid string required

The universally unique identifier (UUID) assigned to a client authentication session.

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' \
--data-raw '{
  "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
  "email": "jdoe@example.com",
  "password": "Secret123",
  "device_fingerprint": "dwqdnNFJBOEBFJEBjqewbkjqbdwjqwbndjnbj"
}'

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

An array of objects specifying whether any of the available 2FA methods are enabled for a client.

The available 2FA methods include:

  • the Google Authenticator app

  • SMS codes

Show object fields
name string

The 2FA method name.

localizedCaption string

The localized name of a 2FA method, displayed to clients in the B2Core UI.

enabled boolean

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

done boolean

If true, authentication has succeeded; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a client authentication session.

workflow string

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

  • login — authentication succeeded; the access and refresh tokens were obtained.

  • 2fa — authentication must be completed by using one of the enabled 2FA methods.

    If both 2FA methods (the Google Authenticator app and SMS codes) are enabled for a client, choose which 2FA method should be used for authentication, and then complete 2FA with a selected method (see Two-factor authentication to learn more).

  • reset_password_email — authentication didn’t succeed because a client had been requested to reset their password by the Back Office admin (see Reset a password from the Sign In page to learn more).

RESPONSE EXAMPLE 
{
  "code": 202,
  "data": {
    "accessToken": {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwiaWF0IjoxNjU2MDY3MTU0LCJleHAiOjE2NTYxMDMxNTQsImlzcyI6Imh0dHBzOlwvXC9hcC52ZW5kb3IuY29tIn0.u6HuS_oQ4udk2EEUa-7XutJ0CAKIZty1OcFaqTckLRGYEr3xcWXZEHCfrhDl31N6_t0XP6_m-ESue_NoWx_f1sGMv6XMT0pPg1NQ1XJ1JJ4slaeEWjSuGIl8_Jbj-20zZOvwzUZbed7UQg0jUM11OUt0l1jVVSF19vKJJpVGFDYMIOHkS7tlFeKiypReYRd2af-Pf_au1v6vG3V42SFpZER3eKqALZkoT617B35enJdtUqmyrRgb_rCIOCwAHQdUcOuosyBUk9U-Cz3WEoHx5nqtvFVAeXKqlbn0Cbqk4joFt1FY8nUqlyVZNI9E3-dbjFPzod8Vej6rkAVd312M3w",
      "createdAt": "2022-01-01T00:00:00+00:00",
      "expiresAt": "2022-01-01T00:00:00+00:00"
    },
    "refreshToken": {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwiaWF0IjoxNjU2MDY3MTU0LCJleHAiOjE2NTYxMDMxNTQsImlzcyI6Imh0dHBzOlwvXC9hcC52ZW5kb3IuY29tIn0.u6HuS_oQ4udk2EEUa-7XutJ0CAKIZty1OcFaqTckLRGYEr3xcWXZEHCfrhDl31N6_t0XP6_m-ESue_NoWx_f1sGMv6XMT0pPg1NQ1XJ1JJ4slaeEWjSuGIl8_Jbj-20zZOvwzUZbed7UQg0jUM11OUt0l1jVVSF19vKJJpVGFDYMIOHkS7tlFeKiypReYRd2af-Pf_au1v6vG3V42SFpZER3eKqALZkoT617B35enJdtUqmyrRgb_rCIOCwAHQdUcOuosyBUk9U-Cz3WEoHx5nqtvFVAeXKqlbn0Cbqk4joFt1FY8nUqlyVZNI9E3-dbjFPzod8Vej6rkAVd312M3w",
      "createdAt": "2022-01-01T00:00:00+00:00",
      "expiresAt": "2022-01-01T00:00:00+00:00"
    },
    "tfaProviders": [
      {
        "name": "sms",
        "localizedCaption": "SMS",
        "enabled": false
      },
      {
        "name": "google",
        "localizedCaption": "Google Authenticator",
        "enabled": false
      }
    ]
  },
  "done": true,
  "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
  "workflow": "login"
}

{
    "code": 200,
    "data": {
      "accessToken": {},
      "refreshToken": {},
      "tfaProviders": [
        {
          "name": "sms",
          "localizedCaption": "SMS",
          "enabled": true
        },
        {
          "name": "google",
          "localizedCaption": "Google Authenticator",
          "enabled": true
        }
      ]
    },
    "done": false,
    "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
    "workflow": "2fa"
  }

Refresh the access token

Use this method to refresh the access token.

If the access token has expired, you can use a valid refresh token to obtain a new set of access and refresh tokens.

Note

If you exceed the allowed number of attempts to refresh the access token within a specified time period, you’ll not 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

Body:

refreshToken string required

The refresh token issued for a current client.

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

curl --location --request POST 'https://host.name/api/v2/my/refresh' \
--data-raw '{
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwiaWF0IjoxNjU2MDY3MTU0LCJleHAiOjE2NTYxMDMxNTQsImlzcyI6Imh0dHBzOlwvXC9hcC52ZW5kb3IuY29tIn0.u6HuS_oQ4udk2EEUa-7XutJ0CAKIZty1OcFaqTckLRGYEr3xcWXZEHCfrhDl31N6_t0XP6_m-ESue_NoWx_f1sGMv6XMT0pPg1NQ1XJ1JJ4slaeEWjSuGIl8_Jbj-20zZOvwzUZbed7UQg0jUM11OUt0l1jVVSF19vKJJpVGFDYMIOHkS7tlFeKiypReYRd2af-Pf_au1v6vG3V42SFpZER3eKqALZkoT617B35enJdtUqmyrRgb_rCIOCwAHQdUcOuosyBUk9U-Cz3WEoHx5nqtvFVAeXKqlbn0Cbqk4joFt1FY8nUqlyVZNI9E3-dbjFPzod8Vej6rkAVd312M3w"
}'

Response

accessToken object or null

The details about the access token.

Show object fields
token string

The access 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.

refreshToken object or null

The details about the refresh token.

Show object fields
token string

The 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.

RESPONSE EXAMPLE 
{
  "accessToken": {
    "token": "wyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwiaWF0IjoxNjU2MDY3MTU0LCJleHAiOjE2NTYxMDMxNTQsImlzcyI6Imh0dHBzOlwvXC9hcC52ZW5kb3IuY29tIn0.u6HuS_oQ4udk2EEUa-7XutJ0CAKIZty1OcFaqTckLRGYEr3xcWXZEHCfrhDl31N6_t0XP6_m-ESue_NoWx_f1sGMv6XMT0pPg1NQ1XJ1JJ4slaeEWjSuGIl8_Jbj-20zZOvwzUZbed7UQg0jUM11OUt0l1jVVSF19vKJJpVGFDYMIOHkS7tlFeKiypReYRd2af-Pf_au1v6vG3V42SFpZER3eKqALZkoT617B35enJdtUqmyrRgb_rCIOCwAHQdUcOuosyBUk9U-Cz3WEoHx5nqtvFVAeXKqlbn0Cbqk4joFt1FY8nUqlyVZNI9E3-dbjFPzod8Vej6rkAVd312M3w",
    "createdAt": "2022-01-01T00:00:00+00:00",
    "expiresAt": "2022-01-01T00:00:00+00:00"
  },
  "refreshToken": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwiaWF0IjoxNjU2MDY3MTU0LCJleHAiOjE2NTYxMDMxNTQsImlzcyI6Imh0dHBzOlwvXC9hcC52ZW5kb3IuY29tIn0.u6HuS_oQ4udk2EEUa-7XutJ0CAKIZty1OcFaqTckLRGYEr3xcWXZEHCfrhDl31N6_t0XP6_m-ESue_NoWx_f1sGMv6XMT0pPg1NQ1XJ1JJ4slaeEWjSuGIl8_Jbj-20zZOvwzUZbed7UQg0jUM11OUt0l1jVVSF19vKJJpVGFDYMIOHkS7tlFeKiypReYRd2af-Pf_au1v6vG3V42SFpZER3eKqALZkoT617B35enJdtUqmyrRgb_rCIOCwAHQdUcOuosyBUk9U-Cz3WEoHx5nqtvFVAeXKqlbn0Cbqk4joFt1FY8nUqlyVZNI9E3-dbjFPzod8Vej6rkAVd312M3w",
    "createdAt": "2022-01-01T00:00:00+00:00",
    "expiresAt": "2022-01-01T00:00:00+00:00"
  }
}

Sign out of the B2Core UI

Use this method to sign out of the B2Core UI.

Request

Header parameters:

  • Authorization: Bearer <access_token>

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

curl --location --request POST 'https://host.name/api/v2/my/signout' \
--header 'Authorization: Bearer <token>'

Response

In case of success, HTTP code 200 is returned.

If the access token issued for a current client was revoked or expired, HTTP code 401 is returned.

Reset a password from the Sign In page

After a client is requested to reset their password by the Back Office admin, use this method to start a password reset procedure for the client.

Request

Header parameters:

  • Content-Type: application/json

  • Accept: application/json

Body:

uuid string required

The universally unique identifier (UUID) obtained after initializing the Sign In Wizard.

action string required

Specify code to indicate that a verification code is required to reset a password.

code string required

The verification code sent to a client email address.

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

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

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 a password was successfully reset for a client, the details about the client.

done boolean

If true, authentication has succeeded; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a client authentication session.

workflow string

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

reset_password — indicates that a new password must be set up for the client to sign in to the B2Core UI.

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

Set up a new password from the Sign In page

After a client is requested to reset their password by the Back Office admin, use this method to set up a new password for the client.

Request

Header parameters:

  • Content-Type: application/json

  • Accept: application/json

Body:

password string required

A new password.

passwordConfirmation string required

The repeatedly specified new password.

uuid string required

The universally unique identifier (UUID) obtained after initializing the Sign In Wizard.

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

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

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 a password was successfully reset for a client, the details about the client.

done boolean

If true, authentication has succeeded; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a client authentication session.

workflow string

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

The client can sign in to the B2Core UI using the new password. To do this, initialize the Sign In Wizard again, and then use the method to sign in to the B2Core UI.

RESPONSE EXAMPLE 
{
  "code": 202,
  "data": {
    "client": {
        "id": 1,
        "email": "jdoe@example.com",
        "settings": {}
    }
  }, 
  "done": true,
  "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
  "workflow": "login"
}

Get a QR code sign-in channel

Use this method to get the sign-in channel that is used to monitor the client’s authentication status when signing in to the B2Core UI using a QR code.

Request

Header parameters:

  • Accept: application/json

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

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

Response

id string

The universally unique identifier (UUID) assigned to the sign-in channel.

lifetimeMinutes integer

The channel lifetime, in minutes.

ip string

The client’s IP address.

location string or null

The client city that is determined based on the IP address.

RESPONSE EXAMPLE 
{
  "id": "0a4682f9-7e6c-49a7-b946-db58f28d8171",
  "lifetimeMinutes": 2,
  "ip": "127.0.0.1",
  "location": null
}

Get an authorization token for signing in using a QR code

Use this method to get the authorization token required to sign in to the B2Core UI using a QR code.

To get the authorization token, a client must already be authenticated in the mobile app.

Request

Header parameters:

  • Content-Type: application/json

  • Authorization: Bearer <token>

Body:

channelId string required

The identifier of the sign-in channel.

To get the identifier, use the method to get a QR code sign-in channel.

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

curl --location --request POST 'https://host.name/api/v2/my/signin/tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
  "channelId": "0a4682f9-7e6c-49a7-b946-db58f28d8171"
}'

Response

In case of success, HTTP code 201 is returned.

The generated authorization token is returned after the qr_code_login WebSocket event is triggered.

Sign in using a QR code

Use this method to obtain a pair of access and refresh tokens.

Request

Header parameters:

  • Content-Type: application/json

  • Accept: application/json

Body:

deviceFingerprint string required

The free-form JSON data (which includes the required user_agent field) generated by the 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.

authorizationToken string required

The authorization token generated for the client.

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

curl --location --request POST 'https://host.name/api/v2/my/signin/qrcodes' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "deviceFingerprint": "eyJ1c2VyX2FnZW50IjoiTW96aWxsYVwvNS4WIChXaW5kb3dZIE5UIDYUMTSgV2luNjQ7IHg2NDsgcnY6NDCUMCkR2Vja29cLzIwMTAwMTAXIEZpcmVmb3hcLzQ3LjAifQ==",
  "authorizationToken": "$2y$10$qZqqwQqqEX7X6nsPLfPkte2pB6gSHazY1v2CLutwBGWCeF4J6ZG06"
}'

Response

clientId integer

The client identifier.

tokens object

The details about tokens.

Show object fields
accessToken object

The details about the access token.

Show object fields
token string

The access 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.

refreshToken object

The details about the refresh token.

Show object fields
token string

The 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.

RESPONSE EXAMPLE 
{
  "clientId": 1,
  "tokens": {
    "accessToken": {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwiaWF0IjoxNjU2MDY3MTU0LCJl",
      "createdAt": "2023-01-01T00:00:00+00:00",
      "expiresAt": "2023-01-01T00:00:00+00:00"
    },
    "refreshToken": {
      "token": "eHAiOjE2NTYxMDMxNTQsImlzcyI6Imh0dHBzOlwvXC9hcC52ZW5kb3IuY29tIn0.u6HuS_oQ4udk2",
      "createdAt": "2023-01-01T00:00:00+00:00",
      "expiresAt": "2023-01-01T00:00:00+00:00"
    }
  }
}