Authentication and Authorization
Last updated
Last updated
The Sentiance Cloud API speaks GraphQL via the endpoint.
An Authorization header with value Bearer <token> authenticates and authorizes your request. The token can either be an API Key or an SDK User Token. SDK User Tokens have access to all queries and mutations available in a single user context. API Keys can access all queries and mutations for the App to which they belong.
SDK Users are created during . They have a UserID and are only authenticated by their token. You can retrieve this token from an initialized SDK after user creation.
API Keys are secure, revocable, and scope-restricted credentials used for user registration, data queries (including offload fetching), user deletion and any other backend-to-backend operation. They are created for a specific Sentiance App, regardless of which Insights Control Tower user generates them.
Users with Developer permissions on a Sentiance App can create API Keys by specifying a name, scope, and expiry date. Each key is disclosed only once—to its creator—so it must be securely stored immediately. While only the creator initially sees the key, any user with Developer permissions on the App can later revoke it.
API Keys should be stored securely and should never be shared outside your company. A Sentiance employee will never ask for your API Key(s). Any leaked key (even to Sentiance employees) will immediately be revoked and flagged as a security incident.
An API Key consists of the following parts.
A name can be given by the developer generating the key. The name is for visual purposes only and has no operational impact. Choose a name that would help you identify the key.
Scopes
Scopes allow you to specify what operations an API Key can perform. Currently, we offer 5 different scopes: USER_READ, USER_DELETE, USER_LINK, OFFLOADS_READ, and OFFLOADS_GENERATE_URL. We strongly recommend that you use multiple API Keys with limited scopes for different operations.
USER_READ
USER_DELETE
USER_LINK
Use this scope to perform User Registration.
OFFLOADS_READ
Use this scope to list Offloads available for download.
OFFLOADS_GENERATE_URL
Use this scope to generate URLs at which offloads can be downloaded.
FAKE_DATA_INSERT
Use this scope to inject fake data.
Expiry Period
For increased security, API Keys are self-expiring. The expiry time is 1 year from the time of creation. After 1 year, the old API Key will stop working and a new one will have to be created. We allow up to 10 active API Keys at any given time, per app. An active key is one that hasn't been revoked or expired.
Please make sure you add the renewal of API Keys to your existing maintenance process and keep track of expiry dates. Developers on your account will receive a reminder e-mail two weeks before the expiry date and one week before the expiry date.
Use this scope to read user data. This scope should be used with the .
Use this scope to delete a user along with all historical data. This scope should be used with the .
You can manage your own API Keys from . The Insights-Control-Tower has all the tools you need, including a full history of API Keys created, revoked, or expired.
Other portals are available for specific regions. For our US customers, please use . For our Indian customers, please use