Baxi Authentication

We provide two mechanism to authenticate business to be able to access our B2B API endpoints.

  1. Api Key Authentication

  2. HMAC Authentication

Any of the two authentication mechanism can be used.

1. API KEY

To be able to use API_KEY as your authentication mechanism, we need to configure a VPN, between us and yourself for communication, and register your IP address with us to keep connection between the two endpoints secure.

This mechanism uses either the standard HTTP "Authorization" header to pass authentication information or the "x-api-key" to pass the api key information.

Sample Usage:

Authorization: Api-key YOUR-API-KEY-GOES-HERE

or

Sample Usage (2)

x-api-key: YOUR-KEY-GOES-HERE

2. Hash Based message Authentication (HMAC)

This authentication method is used in an environment where there is no VPN, a dedicated IP or on a shared server. A user secret is given to you, which will be used to calculate the digest hash that will be sent as headers on every request. No two requests will have the same digest.

The HMAC uses the standard HTTP "Authorization" header to pass authentication information. (The name of the standard header is unfortunate because it carries authentication information, not authorization.) Under the BAXI authentication scheme, the Authorization header has the following form.

Authorization: 'Baxi [BAXI USERNAME]:Signature'

Authorization: Baxi testuser:ONXpnbbudYgopBvRwPFCn7eZTPY=

An extra Http Header "baxi-date": current date/time in RFC 1123 format is also passed along with the request.

baxi-date: Thu, 19 Dec 2019 17:40:26 GMT

How To Calculate Baxi HMAC Digest Signature

  1. Request Type: ("GET" or "POST")

  2. End point to access: /api/baxipay/superagent/account/balance

  3. Request Date in RFC 1123 format: Thu, 19 Dec 2019 17:40:26 GMT

  4. Json Payload (if available): { "name":"tayo" }

  5. Your User Secret: "YOUR_USER_SECRET"

STEP 1: Convert the Date format in (3) above to timestamp.

Timestamp = ConvertToTimestamp("Thu, 19 Dec 2019 17:40:26 GMT")

STEP 2: Do a SHA-256 Hash of your JSON Payload in (4) above. (if applicable)

PAYLOAD_HASH = Hash("SHA-256", JSON_PAYLOAD)

STEP 3: Encode the Payload_Hash in Base 64 (if applicable)

ENCODED_PAYLOAD = ConvertToBase64(PAYLOAD_HASH)

STEP 4: Create a security string for the current request

SECURED_STRING = REQUEST_TYPE + ENDPOINT + TIMESTAMP + ENCODED_PAYLOAD;

STEP 5: Do a UTF-8 ENCODING of the Secured String

ENCODED_SECURED_STRING = Encode_UTF8(SECURED_STRING)

STEP 6: Sign the encoded secured string using HMAC (SHA-1) with your user secret

HASH_SIGNATURE = HASH_HMAC_SHA1( Key: YOUR_USER_SECRET, Message: ENCODED_SECURED_STRING )

STEP 7: Convert the HASH_SIGNATURE to base 64.

FINAL_SIGNATURE = ConvertToBase64(HASH_SIGNATURE)