Home API guide Authentication

Authentication

Obtain token

Note

API credentials are sent to your e-mail after registration. You can regenerate them anytime in Control panel > API Access.

Request

login string required

Your API key.

password string required

Your API secret.

POST[base]/token/

curl --request POST \
--url [base]/token/ \
--header 'Content-Type: application/vnd.api+json' \
--data '{
  "data": {
    "type": "auth-token",
    "attributes": {
      "login": "<Your API key>",
      "password": "<Your secret>"
    }
  }
}'

import requests

url = '[base]/token/'

headers = {
  'content-type': 'application/vnd.api+json',
}

data = {
  'data': {
    'type': 'auth-token',
    'attributes': {
      'login': '<Your API key>',
      'password': '<Your API secret>',
    }
  }
}

requests.post(url, headers=headers, json=data)

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new GuzzleHttp\Client();
try {
  $res = $client->post('[base]/token/', [
    'json' => [
      'data' => [
        'type' => 'auth-token',
        'attributes' => [
          'login' => '<Your API key>',
          'password' => '<Your API secret>',
        ],
      ],
    ],
    'headers' => [
      'Content-Type' => 'application/vnd.api+json',
    ],
  ]);
echo $res->getBody();
} catch (RequestException $e) {}

Response

access string

Your access token. It has an expiry time of about a minute and after expiration should be refreshed.

refresh string

The long-living token that is used for obtaining new access tokens (refer to Refresh token).

access_expired_at string

The date and time of access token expiration.

refresh_expired_at string

The date and time of refresh token expiration.

is_2fa_confirmed boolean

If true, 2FA is enabled.

2FA isn’t available for API users.

time string

The date and time of request receiving.

sign string

The HMAC signature for a response payload authentication.

To verify that the refresh token was sent by B2BinPay, generate an HMAC signature using the sha256 as algorithm: sha256 hash of the concatenation of your login and password as a key, and the concatenation of meta.time and refresh fields as a message.

Refer to Auth verification below for a sign verification example.

RESPONSE BODY EXAMPLE

{
  "data": {
    "type": "auth-token",
    "id": "0",
    "attributes": {
      "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      "access_expired_at": "2020-12-29T05:42:11.925654Z",
      "refresh_expired_at": "2020-12-29T11:27:11.925654Z",
      "is_2fa_confirmed": false
    }
  },
  "meta": {
    "time": "2020-12-29T05:27:11.925654Z",
    "sign": "bcd6519ce27fed2ce9efe49cd09b387f050c0122c96..."
  }
}

Response codes

HTTP code	Application code	Description	Suggested action
200	—	The request succeeded.	—
400	2006: No active account found with the given credentials.	Incorrect credentials.	Send correct credentials.
429	throttled: Request was throttled.	Too many requests.	Try again later.
500	—	Internal server error.	Try again later.
502	—	Bad gateway.	Try again later.
503	—	Service unavailable.	Try again later.
504	—	Gateway timeout.	Try again later.
5xx	—	Other server errors.	Try again later.

---

Refresh token

Important

Once you receive a new key pair using your refresh token, the previous refresh token can no longer be used. A refresh token that is found to be invalid while not being expired must be rendered suspicious.

Request

refreshstring required

Your refresh token from the Obtain token response.

POST[base]/token/refresh/

curl --request POST \
--url [base]/token/refresh/ \
--header 'Content-Type: application/vnd.api+json' \
--data '{
  "data": {
    "type": "auth-token",
    "attributes": {
      "refresh": "<Your refresh token>"
    }
  }
}'

import requests

url = '[base]/token/refresh/'

headers = {
  'content-type': 'application/vnd.api+json',
}

data = {
  'data': {
    'type': 'auth-token',
    'attributes': {
      'refresh': '<Your refresh token>',
    },
  },
}

requests.post(url, headers=headers, json=data)

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new GuzzleHttp\Client();
try {
  $res = $client->post('[base]/token/refresh/', [
    'json' => [
      'data' => [
        'type' => 'auth-token',
        'attributes' => [
          'refresh' => 'Your refresh token',
        ],
      ],
    ],
    'headers' => [
      'Content-Type' => 'application/vnd.api+json',
    ],
  ]);
echo $res->getBody();
} catch (RequestException $e) {}

Response

The response body is the same as for Obtain token request, but without meta fields.

RESPONSE BODY EXAMPLE

{
  "type": "auth-token",
  "id": "0",
  "attributes": {
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "access_expired_at": "2020-12-29T05:42:11.925654Z",
    "refresh_expired_at": "2020-12-29T11:27:11.925654Z",
    "is_2fa_confirmed": false
  }
}

Response codes

HTTP code	Application code	Description	Suggested action
200	—	The request succeeded.	—
401	2007: No active account found with the given credentials.	Incorrect credentials.	Send correct credentials.
500	—	Internal server error.	Try again later.
502	—	Bad gateway.	Try again later.
503	—	Service unavailable.	Try again later.
504	—	Gateway timeout.	Try again later.
5xx	—	Other server errors.	Try again later.

---

Auth verification

Refer to the example below for a sign verification instance.

Auth verification example

// "crypto-js": "4.0.0" is installed as a dependency
const SHA256 = require("crypto-js/sha256");
const hmacSHA256 = require('crypto-js/hmac-sha256');

// set API user login and password
const login = 'Your API key';
const password = 'Your API secret';

// parse /api/token/ response payload
const authResponse = JSON.parse("{\n" +
    "  \"data\": {\n" +
    "    \"type\": \"auth-token\",\n" +
    "    \"id\": \"0\",\n" +
    "    \"attributes\": {\n" +
    "      \"refresh\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUz\",\n" +
    "      \"access\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI\",\n" +
    "      \"access_expired_at\": \"2020-08-24T13:50:12.192479+03:00\",\n" +
    "      \"refresh_expired_at\": \"2020-08-24T19:33:33.192479+03:00\",\n" +
    "      \"is_2fa_confirmed\": false\n" +
    "    }\n" +
    "  },\n" +
    "  \"meta\": {\n" +
    "    \"time\": \"2020-08-24T10:33:33.192479Z\",\n" +
    "    \"sign\": \"e70adec551e26b560049e42aa0993ae42cac4e03fbbb300320d8be\"\n" +
    "  }\n" +
    "}");
    
// prepare data for hash check
const message = authResponse['meta']['time'] + authResponse['data']['attributes']['refresh'];
const responseSign = authResponse['meta']['sign'];
const secret = SHA256(login + password);
const calculatedSign = hmacSHA256(message, secret).toString();

// print result
if (responseSign === calculatedSign) {
  console.log('Verified');
} else {
  console.log('Invalid sign');
}