Authentication
The authentication process at Imburse consists of the following steps:
Access Tenant Portal
Access the Tenant portal. To do so, select the Tenant Portal 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:
- In the Tenant portal, navigate to the left-sidebar menu.
- Select API Keys under Developers.
- Click the 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.
- Give your Tenant API keys a meaningful name. For example:
- Specify the roles required for the API keys by selecting an appropriate checkbox. It is possible to select more than one checkbox.
- Click . Your API keys are created.
- 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.
- 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
}
- 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:
Header | Value |
---|---|
Authorization | Bearer <your bearer token> |
x-account-id | <your account id> |
x-tenant-id | <your tenant id> |
Step 4. Add the Account ID and Tenant ID headers.
To find and copy your Account ID and Tenant ID, perform the following steps:
- In the Tenant portal, navigate to the left-sidebar menu.
- Select Info under Tenant.
- In the Account ID field, click the Copy icon. The confirmation message Account ID is copied to clipboard appears.
- 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
andx-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: