Baxi Authentication

Suggest Edits

We provide two mechanisms to authenticate businesses to be able to access our B2B API endpoints.

  1. API Key Authentication
  2. HMAC Authentication

Any of the two authentication mechanisms can be used.

1. API Key

This is the simplest method to use, and easy to integrate.
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

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

2. Hash Based Message Authentication (HMAC)

For those who wants extra layer of security, This authentication method is usually 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 baxi_test: 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. Endpoint 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): e.g. { "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 an 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)

VPN CONFIGURATION

If you need to configure a VPN, between ourselves and yourself for communication, and register your IP address with us to keep connection between the two endpoints secure, We have a network team, that can make this possible, all you need to do, is to forward your network service request and we resolve to make sure we have an end to end connection.

Updated 6 months ago