Authorization
API Resources
NL Interpreter
Search
Assist
Auth API Overview
The Authorization API grants and maintains authorization for all Inbenta APIs except Agent Chat (For more information, see the Agent Chat 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.
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.
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.
Note
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.
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:
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);
Note
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.
For examples, please refer to the SDK Setup documentation specific to Chat, Knowledge or Search, depending on the product you are using.