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 and TEST 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.

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:

Request parameters

Request example

{
  "recipient": "61401629754",
  "channel": "string",
  "sender": "SENDER",
  "sender_alt": "SENDER_ALT",
  "message_text": "Your verification code: {code}",
  "message_alt_text": "Your alternative code: {code}",
  "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}",
    "message_alt_text": "Your alternative 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"
  }
}

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:

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}",
    "message_alt_text": "Your alternative 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"
  }
}

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}",
    "message_alt_text": "Your alternative 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"
  }
}

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}",
    "message_alt_text": "Your alternative 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"
  }
}

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:

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.",
      "message_alt_text": "string",
      "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",
          "text": "Your verification code: {code}",
          "price": 0.0642918,
          "currency": "EUR",
          "sent_at": "2022-04-18 11:00:30",
          "created_at": "2022-04-18 10:55:35"
        }
      ]
  }
}

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:

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.",
      "message_alt_text": "string",
      "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",
          "text": "Your verification code: {code}",
          "price": 0.0642918,
          "currency": "EUR",
          "sent_at": "2022-04-18 11:00:30",
          "created_at": "2022-04-18 10:55:35"
        }
      ]
    },
    "total": 100
  }
}

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

{
  "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": [
    ...
  ]
}