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 instance's API credentials in the Help Center.
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.
All requests to Inbenta APIs endpoints must be authenticated and authorized:
There are three types of keys: API key, API secret and Domain key:
All requests must be authenticated to access the Inbenta APIs. To do this, send the API key in a
Requests must be authorized. To do this, you exchange either your Secret or your Domain Key for an access token.
/auth endpoint to obtain the access token. The token authorizes all requests to other API endpoints, with the format
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.
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.
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.
When you add a new Domain Key, it can take between 5 to 20 minutes for the key to propagate before you can test or use it. If you experience longer delays, contact Inbenta Support.
Once you have the access token, add it to all following requests inside the authorization header, with the format
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.
• 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_INVALID_ACCESS_TOKEN||Something went wrong. Please, refresh the page||Notification body|
It is possible to change this behaviour by rewriting the function calling this message. This function is:
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.