Auth API

The Authorization API grants and maintains authorization for all Inbenta APIs except Hyperchat (For more information, see the Hyperchat API section). It also obtains the endpoints of the different API products for a given project. This API is accessible at https://api.inbenta.io/v1.

To obtain your credentials, see Finding your API credentials in the Help Center.

Important: This page describes the default setup, which is suitable for most configurations. Other regions and endpoints are available and may be more suitable depending on your use case. For more information, see Regions and Endpoints. If you have any question or doubt, contact your Inbenta representative.

Note: Jump directly to the bottom of the page for examples.

1. Authentication and Authorization Keys

All requests to Inbenta APIs endpoints must be authenticated and authorized:

  • Authentication is the method that the APIs use to identify you.
  • Authorization gives you the access token that manages your session.

There are three types of keys: API key, API secret and Domain key:

  • The API key identifies you.
  • The Secret grants access to your instance's data, but only for requests coming from your own server.
  • The Domain Key grants access to your instance's data, but only for requests coming from a browser (client-side integrations) and from a limited set of domains.

2. Using the keys

a. Requesting Authentication

All requests must be authenticated to access the Inbenta APIs. To do this, send the API key in a x-inbenta-key header.

b. Requesting Authorization

Requests must be authorized. To do this, you exchange either your Secret or your Domain Key for an access token.

Use the /auth endpoint to obtain the access token. The token authorizes all requests to other API endpoints, with the format Bearer <your_access_token>.

i. Using a Secret

You need a client-side request to https://api.inbenta.io/v1/auth to do this. To perform this request, send your Secret into the request body.

Caution: Your Secret must remain confidential. To prevent third parties from accessing your API, always perform this request in a server-side environment. Never expose your secret in client-side integrations.

ii. Using a Domain Key

The Domain Key only grants access to requests coming from the browser (client-side integrations) and from a limited set of domains. The Inbenta SDKs handle the integration for you automatically. If you do not need a custom integration, check the SDK documentation.

You need a client-side request to https://api.inbenta.io/v1/auth to do this. To perform this request, use a js-client to send your Domain Key into the request body.

c. Using the access token

Once you have the access token, add it to all following requests inside the authorization header, with the format Bearer <access_token>;.

i. Refreshing the token

The access token has an expiration period. This period is defined in the token’s expiration attribute. The expiration period is defined by Inbenta and cannot be modifed.

To continue using the APIs, send a refreshToken request to https://api.inbenta.io/v1/auth to receive a new access token before this period elapses.

Caution:

  • If you obtained your access token with your Secret, always perform a server-side request. To refresh the access token before it expires, you can use the refreshToken endpoint of the Auth API. This operation can be performed on server-side or client-side but Inbenta strongly recommends that you do it on server-side. Remember that you must never expose your secret in client-side integrations.
  • If you obtained your access token with a Domain Key, you should perform the access token request in a client-side in one of the domains related to the Domain Key. In this case, Inbenta recommends that you refresh the access token only when it is expired and must do a request to the product API.
  • Do not perform this request after every API call, or you will quickly exceed the rate limits. Inbenta recommends refreshing the access token between 1 and 3 minutes before the end of the expiration period.

Note: If you use the SDK, it will refresh the access token automatically when possible. Note that it might not be possible to refresh the token under certain circumstances, such as when the computer is in sleep mode. If the access token can not be refreshed before it expires, the token will not be refreshed at all, and the following message appears:

refresh error

Labels

Notification labels:

Name Default Description
REFRESH_TITLE Oooops...! Notification title
REFRESH_INVALID_ACCESS_TOKEN Something went wrong. Please, refresh the page Notification body
REFRESH_BUTTON Refresh: Notification button

It is possible to change this behaviour by rewriting the function calling this message. This function is:

 sdk.setCallbackWhenInvalidAccessToken(callback:Function);

Example:

If you create the SDK with an access token, you must call the server before it expires to receive a new access token. If the function returns a promise and the access token cannot be refreshed, it will retry the calls made while the token was valid. For more information, consult Promises support.

In this example, the AJAX call returns the same access token and expiration as the endpoint does. The response is in JSON format:

sdk.setCallbackWhenInvalidAccessToken(function(){
  return new Promise((resolve, reject) => {
    var xhttp = new XMLHttpRequest();
    xhttp.addEventListener( 'load', function() {
      if (this.readyState == 4 && this.status == 200) {
        var object = JSON.parse(this.responseText);
        sdk.client.setAccessToken(object.accessToken, object.expirationAt);
        resolve('success');
      } else {
        reject('error');
      }
    });
    xhttp.open("GET", "?action=getAccesToken", true);
    xhttp.send();
  });
});