Authentication and Authorization
The Sentiance Cloud API speaks GraphQL via the https://api.sentiance.com/v4/gql 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.
Example:
Authorization: Bearer e5c3b842231543f.mGCUhfi0uI4J13k010V49D2GaBZ3j1E708X4a4396XNx48X3SDK User Tokens
SDK Users are created during SDK User Creation. 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
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.
Name
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
Use this scope to read user data. This scope should be used with the GraphQL API.
USER_DELETE
Use this scope to delete a user along with all historical data. This scope should be used with the user delete API.
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.
Manage Your Own API Keys
You can manage your own API Keys from Insights-Control-Tower. The Insights-Control-Tower has all the tools you need, including a full history of API Keys created, revoked, or expired.
Last updated