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.

POST[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

Initialize the Sign In Wizard

Use this method to initialize the Sign In Wizard for a client and specify the fields displayed on the login form.

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 in a progression of wizard pages:

  • 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

Contains a recaptcha object providing the following field:

enabled boolean

If true, reCAPTCHA is added to the authorization form displayed for a client; 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": 202,
  "data": {
    "recaptcha": {
      "enabled": false
    }
  },
  "done": true,
  "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.

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": "foo@bar.com",
  "password": "Secret123",
  "device_fingerprint": "dwqdnNFJBOEBFJEBjqewbkjqbdwjqwbndjnbj",
  "recaptchaResponse": "in quis cillum nisi"
}'

Response

code integer

An HTTP code specifying the current step in a progression of wizard pages:

  • 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

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.

Note

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

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

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
{
  "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.