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 |
|
POST[host]/api/v2/my/signin |
|
POST[host]/api/v2/my/refresh |
|
POST[host]/api/v2/my/signout |
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 |
|
POST[host]/api/v2/my/signin/password/reset |
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 |
|
POST[host]/api/v2/my/signin/tokens |
|
POST[host]/api/v2/my/signin/qrcodes |
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 clientHTTP 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.
{
"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 clientHTTP 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).
{
"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.
{
"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 clientHTTP 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.
{
"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 clientHTTP 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.
{
"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.
{
"id": "0a4682f9-7e6c-49a7-b946-db58f28d8171",
"lifetimeMinutes": 2,
"ip": "127.0.0.1",
"location": null
}
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.
{
"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"
}
}
}