Authenticate your API Requests

We recommend that you use the sandbox environment for accessing the Tenant portal, if you are trying to authenticate your API request for the first time.

The Imburse platform uses a secure and robust authentication process to validate API calls. To prevent unauthorized parties from using your account, the Imburse platform uses multi-step authentication method.

Before you Start

Before you start following this guide, we assume that you have generated your Tenant API Key.

How it works?

Before making any calls to the Imburse APIs, you must generate a HMAC Token. HMAC token is used by Imburse platform to securely and uniquely identify you.

However, generating and verifying an HMAC token for every single API request is computationally expensive.

So to speed up the process, Imburse platform asks you to submit your HMAC token through our secure HMAC endpoint and offers you an Access Token in return. Using this Access Token, you can make subsequent calls to any other Imburse APIs.

Follow this guide to the end to see how you can generate Access Token using your HMAC token.

How to Authenticate API Requests?

Step 1: Create a HMAC Token

Use your API Key (Private and Public Keys) to create a HMAC token from your request.

You can implement the program to generate HMAC token by yourself. Alternatively, you can use the handy form (below) to generate HMAC token.

Public Key

Private Key

Step 2: Generate an Access Token and Copy it

Make a call to our HMAC endpoint using the HMAC token as a part of Authorization header to generate an Access Token.

API Header SyntaxAPI Header ExampleAPI Response Example

Copy

Copied

Authorization: Hmac {hmactoken}

Copy

Copied

Authorization: Hmac {are299c5u99lf2XQy3GBP57fOzxGmEU90ooveijYIRySP8xKqjM=}

Copy

Copied

{
  "accessToken": "eyJhbGciOiJIUzI1N...9UAUBNuyPN6Xg",
  "expires": 1614350382
}

An Access Token will expire after 120 minutes. Check the expires property of the API response determine how long the Token will remain valid.

If an Access Token has expired, call the HMAC endpoint again to regenerate new Access Token.

Step 3: Build the Request Header

Use the Access Token in the Authorization header of the subsequent API Calls. Most APIs also require x-account-id and x-tenant-id headers as a part of request, where the former indicates your Account ID and the latter indicates your Tenant ID.

API Header SyntaxAPI Header Example

Copy

Copied

Authorization: Bearer {accesstoken}
x-account-id: <your-account-id>
x-tenant-id: <your-tenant-id>
Content-Type: application/json

Copy

Copied

Authorization: Bearer {eyJhbGciOiJIUzI1N...9UAUBNuyPN6Xg}
x-account-id: 49bder42-90d9-46b1-b120-f6b347d621a0
x-tenant-id: 60452f48-5d48-4bc0-ab6f-5cr3ee411f63
Content-Type: application/json

You can copy your Tenant ID and Account ID from the Tenant Info page. To access Tenant Info page, click on the Info submenu under the Tenant menu from the left-sidebar of your Tenant Portal.

Troubleshooting

My access to an endpoint has been denied.

While the error message that you receive as a part of API Response will give you more details on why your access was denied, it will usually happen for one of the following reasons.

You don't have the correct permissions to access the Imburse APIs.
The HMAC token used to generate an Access Token is invalid.
Your Access Token has expired.

To resolve the issue, repeat the authentication steps described above. If that doesn't work contact your Tenant Administrator.

When will my Access Token expire?

See the expires property of HMAC endpoint response, to assess the length of time your Access Token will remain active.

The value shown next to the expires property is Unix (Epoch) timestamp. Use the handy form (below) to convert Unix timestamp to human-readable date.

Epoch