2FA API

BSG 2FA API is a RESTful API for two-factor user authentication on a website or web application: you can use it to confirm a transaction, and user contact information, as a second factor in user authentication, and more.

BSG 2FA API provides a choice of channel for sending a one-time password (OTP) to a user: SMS or Viber. Connect the channel you need in your personal account on the “Settings” page of the “2FA” section and start working with the BSG 2FA API.

Please note: 2FA API is not available for use in DEMO account modes (modes in which your account data is not verified).

Make sure that you have entered all the necessary data in your account settings in order to use the 2FA service.

Available HTTP Methods

1. Send a one-time password;
2. Resend the one-time code;
3. Check the one-time Code;
4. Cancel the authentication session;
5. Check authentication status;
6. Get a list of authentication sessions.
7. Create message template;
8. Delete a message template;
9. Retrieve the list of templates.

Send One-time password

This API call is used to generate and send a one-time password to a user in an SMS or Viber message. Please note: authentication of recipients who are in the SMS or Viber stop list in your contact book is not possible using the corresponding method. (That is, if the recipient is in the SMS stop list, then when requesting authentication using the SMS method, the one-time password will not be sent, and you will receive an error in response).

To send One-time password make a request to this URL:

Be reliable. Use 2FA
Get Started

Request parameters

Request example

{ 

  "recipient": "61401629754", 
  "channel": "string", 
  "sender": "SENDER", 
  "sender_alt": "SENDER_ALT", 
  "template_id": "12", 
  "code_lifetime": 300, 
  "code_max_tries": 3, 
  "code_digits": 5 

}

Response parameters

Response example

Response in case of successful request:

{
  "data": {
    "id": "bf4381c8-9d4a-4705-bd28-f89a830b7f96",
    "recipient": "380979965073",
    "status": "pending",
    "channel": "sms",
    "sender": "SENDER",
    "sender_alt": "SENDER_ALT",
    "message_text": "Your verification code: {code}",
    "code_lifetime": 300,
    "code_max_tries": 3,
    "code_digits": 5,
    "price": "0,02",
    "currency": "USD",
    "country_code": "UA",
    "expired_at": "2023-01-04 18:37:06",
    "created_at": "2023-01-04 17:37:06"
    "finished_at": "2023-01-04 17:37:06"
  }
}

Codes of errors

Resend the one-time code

Used to resend the one-time password to the recipient: a new one-time password is generated and sent in the message, and the previous one becomes invalid. When resending, already saved data is used to generate the OTP from the request https://one-api.bsg.world/api/2fa/authentications/otp

This API call is available only if the current authentication is not completed before its expiration date (the authentication validity period is specified in each 2FA API response).

To resend the one-time code send request to this URL:

Be reliable. Use 2FA
Get Started

Request parameters

Response parameters

Response example

Response in case of successful request:

{
  "data": {
    "id": "bf4381c8-9d4a-4705-bd28-f89a830b7f96",
    "recipient": "380979965073",
    "status": "pending",
    "channel": "sms",
    "sender": "SENDER",
    "sender_alt": "SENDER_ALT",
    "message_text": "Your verification code: {code}",
    "code_lifetime": 300,
    "code_max_tries": 3,
    "code_digits": 5,
    "price": "0,02",
    "currency": "USD",
    "country_code": "UA",
    "expired_at": "2023-01-04 18:37:06",
    "created_at": "2023-01-04 17:37:06"
    "finished_at": "2023-01-04 17:37:06"
  }
}

Codes of errors

Check one-time Code

The API call is used to verify that the one-time password you received from the user matches the one sent by BSG.

To Check one-time Code send request to this URL:

Request parameters

Response parameters

An example of a response if the code is incorrect:

{
  "errors": [
    {
      "message": "The code does not match the expected value"
    }
  ]
}

If the one-time code is correct:

Response example

{
  "data": {
    "id": "bf4381c8-9d4a-4705-bd28-f89a830b7f96",
    "recipient": "380979965073",
    "status": "pending",
    "channel": "sms",
    "sender": "SENDER",
    "sender_alt": "SENDER_ALT",
    "message_text": "Your verification code: {code}",
    "code_lifetime": 300,
    "code_max_tries": 3,
    "code_digits": 5,
    "price": "0,02",
    "currency": "USD",
    "country_code": "UA",
    "expired_at": "2023-01-04 18:37:06",
    "created_at": "2023-01-04 17:37:06"
    "finished_at": "2023-01-04 17:37:06"
  }
}

Codes of errors

Cancel the authentication session

Used to cancel the authentication process. In this case, authentication must be in the Pending status.

To cancel the authentication session send request to this URL:

Request parameters

Response parameters

Response example

Response in case of successful request:

{
  "data": {
    "id": "bf4381c8-9d4a-4705-bd28-f89a830b7f96",
    "recipient": "380979965073",
    "status": "canceled",
    "channel": "sms",
    "sender": "SENDER",
    "sender_alt": "SENDER_ALT",
    "message_text": "Your verification code: {code}",
    "code_lifetime": 300,
    "code_max_tries": 3,
    "code_digits": 5,
    "price": "0,02",
    "currency": "USD",
    "country_code": "UA",
    "expired_at": "2023-01-04 18:37:06",
    "created_at": "2023-01-04 17:37:06"
    "finished_at": "2023-01-04 17:37:06"
  }
}

Possible errors

Check authentication status

Use to get information about the current authentication status by specifying its identifier.

To check authentication status send request to this URL:

Be reliable. Use 2FA
Get Started

Request parameters

Response parameters

Response example

Response in case of successful request:

{

  "data": {

      "id": "ea5db413-e368-4952-b745-cc2030210c49", 
      "recipient": "380501403813", 
      "status": "verified", 
      "channel": "sms", 
      "sender": "testsms", 
      "sender_alt": "string", 
      "message_text": "Your BSG 2FA confirmation code is {code}. Do not share this with anyone else.", 
      "code_lifetime": 30, 
      "code_max_tries": 5, 
      "code_digits": 6, 
      "price": 50.25, 
      "currency": "EUR", 
      "country_code": "FR", 
      "expired_at": "2022-04-28 14:21:16", 
      "created_at": "2022-04-28 14:21:16", 
      "updated_at": "2022-04-28 14:21:16", 
      "finished_at": "2022-04-28 14:21:16", 

      "messages": [

        { 
          "id": "1ed32701-5d4f-6cfa-ba06-9db3aa8bab68", 
          "recipient": "61401629754", 
          "status": "accepted", 
          "channel": "sms", 
          "sender": "SENDER", 
          "price": 0.0642918, 
          "currency": "EUR", 
          "sent_at": "2022-04-18 11:00:30", 
          "created_at": "2022-04-18 10:55:35" 

        } 

      ] 

  } 

}

Possible errors

Get a list of authentication sessions

Use to get a list of authentications for a period.

To get a list of authentication sessions make a request to this URL:

Be reliable. Use 2FA
Get Started

Request parameters

Response parameters

Response example

Response in case of successful request:

{
  "data": {
    "list": [
      {
      "id": "ea5db413-e368-4952-b745-cc2030210c49",
      "recipient": "380501403813",
      "status": "verified",
      "channel": "sms",
      "sender": "testsms",
      "sender_alt": "string",
      "message_text": "Your BSG 2FA confirmation code is {code}. Do not share this with anyone else.",
      "code_lifetime": 30,
      "code_max_tries": 5,
      "code_digits": 6,
      "price": 50.25,
      "currency": "EUR",
      "country_code": "FR",
      "expired_at": "2022-04-28 14:21:16",
      "created_at": "2022-04-28 14:21:16",
      "updated_at": "2022-04-28 14:21:16",
      "finished_at": "2022-04-28 14:21:16",
      "messages": [
        {
          "id": "1ed32701-5d4f-6cfa-ba06-9db3aa8bab68",
          "recipient": "61401629754",
          "status": "accepted",
          "channel": "sms",
          "sender": "SENDER",
          "price": 0.0642918,
          "currency": "EUR",
          "sent_at": "2022-04-18 11:00:30",
          "created_at": "2022-04-18 10:55:35"
        }
      ]
    },
    "total": 100
  }
}

Create a message template

This method creates a new message template used for sending the OTP code.

Please note that after creating the template, it is moderated. This template will be available for sending messages with the OTP code only after moderation. Once it’s ready, its status will be changed from Requested to Approved.

To create a message template make a request to this URL:

Request parameters

Request example

{   

   "name": "template name",   

   "countries": ["UA","PT","AD","IT"],   

   "text": "test code is {code2fa}" 

}

Response parameters

Response example

Response in case of successful request:

{

"data": {

     "template_id": 515,

     "name": "template name",

     "text": "test code is {code2fa}",

     "countries": [

             "AD",

             "IT",

             "PT",

             "UA"

           ],

     "status": "requested",

     "updated_at": "2023-06-30 14:52:58"

    }

}

Possible errors

Delete a message template

This method deletes the message template for sending the OTP code based on its unique identifier.

To delete a message template make a request to this URL:

Request parameters

Response parameters

If the request is successful, it returns the answer –- Successfully removed.

Codes of errors

Retrieve the list of templates

This method returns a list of message templates for sending OTR code, allowing you to filter them by various parameters.

To retrieve the list of templates make a request to this URL:

Request parameters

Response parameters

Example of response

Response in case of a successful request:

{

   "data": [

      {

         "template_id": "49",

         "name": "string",

         "countries": [

            "AD",

            "IT",

            "PT",

            "UA"

         ],

         "text": "Your BSG 2FA confirmation code is {code2fa}.",

         "status": "approved",

         "updated_at": "2022-04-18 10:55:35"

      }

   ],

   "total": 1,

   }

}

2FA errors:

One API errors responses:

1.1. Access code expired

1.2. Access code not found

1.3. Authentication canceled status

1.4. Authentication expired

1.5. Authentication failed status

1.6. Authentication invalid status

1.7. Authentication limit with status pending

1.8. Total authentication limit

1.9. Authentication verifying attempts limit

1.10. Authentication not found

1.11. Authentication price not found

1.12. Insufficient funds

1.13. Recipient exists on the stop list

1.14. Authentication channel inactive

1.15. Authentication channel not found

1.16. Template not found

1.17. Default template is not available for deletion

1.18. User has a template with the identical name!

1.19. This action is not available for the account of your type.

1.20. The {code2fa} variable must occur only once in the text

1.21. The variable {code2fa} is required in the text

1.22. The number of requests to create a template is limited to 10. Please wait for the manager approve before making a new request.

{
  "errors": [
    {
      "message": "ERROR_MESSAGE_1"
    }
  ]
}

2. OneAPI validation errors:

{
  "message": "The given data was invalid.",
  "errors": {
    "<FIELD_1>": [
      "<VALIDATION_ERROR_1>"
    ], ...

    "<FIELD_N>": [
      "<VALIDATION_ERROR_N>"
    ]
  }
}

3. OneAPI to 2FA integration errors:

3.1. Raw error 2FA Service response is empty.

3.2. Raw error 2FA Service response has an incorrect content.

3.3. Error 2FA Service response is empty.

3.4. Error 2FA Service response structure is incorrect.

3.5. 2FA Service getting error response error.

3.6. 2FA Service getting successful response error.

3.7. 2FA Service getting response error.

3.8. 2FA Service error.

3.9. 2FA Service getting error response error.

3.10. 2FA Service getting successful response error.

3.11. 2FA Service getting response error.

{
  "message": "<ERROR_MESSAGE>",
  "errors": [
    ...
  ]
}