Home B2Core API Enable or disable 2FA

Enable or disable 2FA

This tutorial provides detailed instructions on enabling 2FA with the Google Authenticator app or SMS codes for clients, as well as disabling them via API. It outlines the specific order in which API methods should be used in each case.

Enable 2FA with Google Authenticator

To enable 2FA with the Google Authenticator app for a client, follow the steps below:

Initialize the wizard for enabling 2FA:

GET[host]/api/v2/my/2fa/{type}/enable/wizard

Enable 2FA with Google Authenticator:

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

Step 1

Initialize the wizard for enabling 2FA.

Request

Header parameters:

Accept: application/json
Accept-Language: <language_code>
Authorization: Bearer <access_token>

Path parameters:

type required: Specify google to enable to 2FA with Google Authenticator.

GET[host]/api/v2/my/2fa/{type}/enable/wizard

curl --location --request GET 'https://host.name/api/v2/my/2fa/google/enable/wizard' \
--header 'Authorization: Bearer <token>' \
--header 'Accept: application/json' \
--header 'Accept-Language: <language_code>'

Response

code integer

An HTTP code specifying the current step of a procedure of enabling 2FA:

HTTP code 200 for an intermediary step after which another page of a form used to enable 2FA is displayed to a client
HTTP code 202 for a final wizard step signaling that 2FA was successfully enabled

data object

The object containing the following data:

Show object fields

qr string: The image data for displaying a QR code that a client can scan using the Google Authenticator app installed on their mobile device to quickly add the account for generating verification codes to their app.
key string: The security key required for enabling 2FA with the Google Authenticator app.

done boolean

If true, 2FA was successfully enabled; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a procedure of enabling 2FA.

workflow string

The string value 2fa_google indicates that you can enable for a client 2FA with Google Authenticator at the next step.

    RESPONSE EXAMPLE — STEP 1
  
{
  "code": 200,
  "data": {
      "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAQAAABXwbpWAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPEhB4iEhBwgEhJygEhIyAEiIRFf+H+k+exnD6YEPwAAAABJRU5ErkJggg==",
      "key": "G7NMO7RKZNS3PXQQ"
  },
  "done": false,
  "uuid": "1c5df3c5-7ee9-44a9-b307-8964b9382d13",
  "workflow": "2fa_google"
}

Step 2

Enable 2FA with Google Authenticator for a client.

Request

Header parameters:

Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>

Request

Body:

uuid string required: The universally unique identifier (UUID) obtained after initializing the wizard for enabling 2FA.
action string required: Specify code.
code string required: The verification code from the Google Authenticator app.
key string required: The security code obtained after initializing the wizard for enabling 2FA.

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

curl --location --request POST 'https://host.name/api/v2/my/2fa/wizard' \
--header 'Authorization: Bearer <token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "uuid": "1c5df3c5-7ee9-44a9-b307-8964b9382d13",
  "action": "code",
  "code": "84112",
  "key": "G7NMO7RKZNS3PXQQ"
}'

Response

code integer

An HTTP code specifying the current step of a procedure of enabling 2FA:

HTTP code 200 for an intermediary step after which another page of a form used to enable 2FA is displayed to a client
HTTP code 202 for a final wizard step signaling that 2FA was successfully enabled

done boolean

If true, 2FA was successfully enabled; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a procedure of enabling 2FA.

workflow string

The string value Terminate indicates that the procedure was successfully completed and 2FA with Google Authenticator was enabled for a client.

    RESPONSE EXAMPLE — STEP 2
  
{
  "code": 202,
  "data": [],
  "done": true,
  "uuid": "1c5df3c5-7ee9-44a9-b307-8964b9382d13",
  "workflow": "Terminate"
}

Enable 2FA with SMS

To enable 2FA with SMS codes for a client, follow the steps below:

Initialize the wizard for enabling 2FA:

GET[host]/api/v2/my/2fa/{type}/enable/wizard

Add a client phone number for use with 2FA:

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

In the request body, specify the uuid and phone parameters.

Confirm the specified phone number and enable 2FA with SMS codes:

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

Use the same method as in step 2; however, specify the uuid, action, and code parameters in the request body.

Step 1

Initialize the wizard for enabling 2FA.

Request

Header parameters:

Accept: application/json
Accept-Language: <language_code>
Authorization: Bearer <access_token>

Path parameters:

type required: Specify sms to enable to 2FA with SMS codes.

GET[host]/api/v2/my/2fa/{type}/enable/wizard

curl --location --request GET 'https://host.name/api/v2/my/2fa/sms/enable/wizard' \
--header 'Authorization: Bearer <token>' \
--header Accept: application/json' \
--header Accept-Language: <language_code>

Response

code integer

An HTTP code specifying the current step of a procedure of enabling 2FA:

HTTP code 200 for an intermediary step after which another page of a form used to enable 2FA is displayed to a client
HTTP code 202 for a final wizard step signaling that 2FA was successfully enabled

done boolean

If true, 2FA was successfully enabled; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a procedure of enabling 2FA.

workflow string

The string value 2fa_sms_phone_create indicates that a client phone number must be added at the next step.

    RESPONSE EXAMPLE — STEP 1
  
{
  "code": 200,
  "data": null,
  "done": false,
  "uuid": "c392816d-255f-48b0-a2b4-b315c30816a5",
  "workflow": "2fa_sms_phone_create"
}

Step 2

Add a client phone number for use with 2FA.

Request

Header parameters:

Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>

Body:

uuid string required: The universally unique identifier (UUID) obtained after initializing the wizard for enabling 2FA.
phone string required: The client phone number for receiving verification codes via SMS.

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

curl --location --request POST 'https://host.name/api/v2/my/2fa/wizard' \
--header 'Authorization: Bearer <token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "uuid": "c392816d-255f-48b0-a2b4-b315c30816a5",
  "phone": "+79994445561",
}'

Response

code integer

An HTTP code specifying the current step of a procedure of enabling 2FA:

HTTP code 200 for an intermediary step after which another page of a form used to enable 2FA is displayed to a client
HTTP code 202 for a final wizard step signaling that 2FA was successfully enabled

data object

The details about a verification code required to confirm a specified phone number.

Show object fields

expiredAt string: The date and time when a verification code is due to expire.
sentAt string: The date and time when a verification code was sent to the specified phone number.
recipient object: The details about a verification code recipient.

done boolean

If true, 2FA was successfully enabled; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a procedure of enabling 2fA.

workflow string

The string value phone indicates that the specified phone number must be confirmed at the next step.

    RESPONSE EXAMPLE — STEP 2
  
{
  "code": 200,
  "data": {
      "status": 0,
      "sent": 3,
      "expiredAt": "2022-12-28T13:00:58.000000Z",
      "sentAt": "2022-12-28T12:50:58.000000Z",
      "recipient": {
          "class": "B2B\\TCA\\Confirmations\\Recipients\\PhoneRecipient",
          "phone": "+79994445561",
          "template": "default",
          "data": null,
          "type": 2,
          "method": "phone"
      }
  },
  "done": false,
  "uuid": "c392816d-255f-48b0-a2b4-b315c30816a5",
  "workflow": "phone"
}

Step 3

Confirm the specified phone number and enable 2FA with SMS codes for a client.

Request

Header parameters:

Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>

Body:

uuid string required: The universally unique identifier (UUID) obtained after initializing the wizard for enabling 2FA.
action string required: Specify code.
code string required: The verification code sent to the specified phone number.

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

curl --location --request POST 'https://host.name/api/v2/my/2fa/wizard' \
--header 'Authorization: Bearer <token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "uuid": "c392816d-255f-48b0-a2b4-b315c30816a5",
  "action": "code",
  "code": "84112",
}'

Response

code integer

An HTTP code specifying the current step of a procedure of enabling 2FA:

HTTP code 200 for an intermediary step after which another page of a form used to enable 2FA is displayed to a client
HTTP code 202 for a final wizard step signaling that 2FA was successfully enabled

done boolean

If true, 2FA was successfully enabled; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a procedure of enabling 2fA.

workflow string

The string value Terminate indicates that the procedure was successfully completed and 2FA with SMS codes was enabled for a client.

    RESPONSE EXAMPLE — STEP 3
  
{
  "code": 202,
  "data": [],
  "done": true,
  "uuid": "c392816d-255f-48b0-a2b4-b315c30816a5",
  "workflow": "Terminate"
}

Disable 2FA

To disable 2FA with Google Authenticator or 2FA with SMS codes for a client, follow the steps below:

Initialize the wizard for disabling 2FA and specify a 2FA method that you want to disable:

GET[host]/api/v2/my/2fa/{type}/disable/wizard

Depending on the workflow of the 2FA disabling procedure, the selected 2FA method may be disabled immediately or may require confirmation with a verification code sent to the client email address or phone number.

For confirmation, use the following method:

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

Step 1

Initialize the wizard for disabling 2FA.

Request

Header parameters:

Accept: application/json
Accept-Language: <language_code>
Authorization: Bearer <access_token>

Path parameters:

type required

The 2FA method that you want to disable for a client. Possible values:

google — 2FA with Google Authenticator app
sms — 2FA with SMS codes

GET[host]/api/v2/my/2fa/{type}/disable/wizard

curl --location --request GET 'https://host.name/api/v2/my/2fa/google/disable/wizard' \
--header 'Authorization: Bearer <token>' \
--header 'Accept: application/json' \
--header 'Accept-Language: <language_code>

Response

code integer

An HTTP code specifying the current step of a procedure of disabling 2FA:

HTTP code 200 for an intermediary step after which another page of a form used for disabling 2FA is displayed to a client
HTTP code 202 for a final wizard step signaling that 2FA was successfully disabled

done boolean

If true, 2FA was successfully disabled; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a procedure of disabling 2FA.

workflow string

A string value indicating the next or final step of a procedure of disabling 2FA. Possible values:

Terminate — indicates that the procedure was successfully completed and the selected 2FA method was disabled for a client.
2fa_email — indicates that a verification code was sent to a client email address. Confirm disabling of the selected 2FA method at the next step.
phone — indicates that a verification code was sent to a client phone number. Confirm disabling of the selected 2FA method at the next step.

    RESPONSE EXAMPLE — STEP 1
  
{
  "code": 200,
  "data": {
      "phone": "+7 999 ***-**-61",
      "confirmation": {
          "id": 868,
          "uuid": "30f8849b-f91f-4425-b8f8-40a0ea43bba2",
          "type": 0,
          "status": 0,
          "entity_type": "phone",
          "entity_id": 871,
          "sent": 17,
          "recipient": {
              "class": "B2B\\TCA\\Confirmations\\Recipients\\PhoneRecipient",
              "phone": "+79994445561",
              "template": "default",
              "data": null,
              "type": 2,
              "method": "phone"
          },
          "confirmed_by": null,
          "done_by": null,
          "sent_at": "2024-04-12T10:33:46.000000Z",
          "expired_at": "2024-04-12T10:43:46.000000Z",
          "confirmed_at": null,
          "done_at": null,
          "created_at": "2022-12-28T07:54:44.000000Z",
          "updated_at": "2024-04-12T10:33:46.000000Z"
      }
  },
  "done": false,
  "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
  "workflow": "phone"
}

Step 2

Confirm disabling of the selected 2FA method for a client with a verification code sent to a client email address or phone number.

Request

Header parameters:

Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>

Request

Body:

uuid string required: The universally unique identifier (UUID) obtained after initializing the wizard for disabling 2FA.
action string required: Specify code.
code string required: The verification code sent to a client email address or phone number.

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

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

Response

code integer

An HTTP code specifying the current step of a procedure of disabling 2FA:

HTTP code 200 for an intermediary step after which another page of a form used for disabling 2FA is displayed to a client
HTTP code 202 for a final wizard step signaling that 2FA was successfully disabled

done boolean

If true, 2FA was successfully disabled; otherwise, false.

uuid string

The universally unique identifier (UUID) assigned to a procedure of disabling 2fA.

workflow string

The string value Terminate indicates that the procedure was successfully completed and the selected 2FA method was disabled for a client.

    RESPONSE EXAMPLE — STEP 2
  
{
  "code": 202,
  "data": [],
  "done": true,
  "uuid": "36f59381-5b54-48bd-a0c7-3b908c476732",
  "workflow": "Terminate"
}