Authentication

The authentication process at Imburse consists of the following steps:

1. Access Tenant Portal
2. Generate API Keys
3. Authenticate API Request

Access Tenant Portal

Access the Tenant portal. To do so, select the Tenant Portal environment:

• Sandbox environment
• Production environment

The Welcome page containing various sections to navigate appears.

Generate API Keys

API (Application Programming Interface) keys are used by the application to authenticate your access to Imburse service. You can create, view and manage your API keys in the Tenant portal.

Create your private and public API keys

Create your private and public API keys. To do so, perform the following steps:

1. In the Tenant portal, navigate to the left-sidebar menu.
2. Select API Keys under Developers.

3. Click the +Add button in the top right corner. A new Add API key page appears. If you have already generated API keys, your public API key will be displayed at this stage.
4. Give your Tenant API keys a meaningful name. For example:
   ​
5. Specify the roles required for the API keys by selecting an appropriate checkbox. It is possible to select more than one checkbox.

6. Click Save. Your API keys are created.
7. Copy your private API key somewhere safe.

As your API keys carry many privileges, do not share your private or secret API key in publicly accessible areas such as GitHub, client-side code, and others. For security reasons, treat it like a password and use it only in server-to-server communication.

Authenticate API Request

For API request authentication, perform the following steps:

Step 1. Create the HMAC Token.

To create the HMAC token from your request, use the combination of your private and public keys. You can generate your HMAC token by using this online form:

To learn more on what HMAC is, see Concepts: HMAC.

Example:

Authorization: Hmac {asd3ad3a3dascwTFOfF7EcDHiz+U/kpf3H7A5FfZ+RfA6FZ3IFA=}

Step 2. Create the Access Token.

1. When the HMAC token is created, create the Access Token by making a request with the following API:

URL

POST /v1/identity/hmac

Headers

Authorization: Hmac {hmac-token}

Response sample

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

2. Copy the accessToken property from the response object. This is your Access Token for accessing APIs.

Step 3. Create the Bearer Authorization request to the API.

With the Access Token returned in Step 2, you can make requests to the API to get a list of Accounts and Tenants the authenticating user has access to:

URL

GET /v1/identity/me

Headers

Most API requests require the following headers:

Step 4. Add the Account ID and Tenant ID headers.

To find and copy your Account ID and Tenant ID, perform the following steps:

1. In the Tenant portal, navigate to the left-sidebar menu.
2. Select Info under Tenant.
3. In the Account ID field, click the Copy icon. The confirmation message Account ID is copied to clipboard appears.
4. Repeat the same action for the Tenant ID field.

Depending on what particular API call requires, proceed as follows:

• If the API call requires the x-account-id header, use the ID of the Account associated with the Account API Key used for the request.
• If the API call requires both the x-account-id and x-tenant-id headers, for the Account ID use the ID of the Account that your Tenant is related to. For the Tenant ID, use the ID of the Tenant associated with the Tenant API Key used for the request.

Troubleshooting

This section gives troubleshooting tips that may be useful if you encounter an issue while making a request to an endpoint:

Your access to an endpoint is denied

Issue: If you make a request to an endpoint that you do not have access to, your request will fail. In this case, you will receive a response containing an appropriate status code along with the error message.

Issue with the Access Token expiration date

Issue: Your request to an endpoint fails as your Access Token is expired.

The token is only valid for 30 minutes, and you can use it only once.

Use this online form to convert your timestamp into a human date-time format: