Authentication and Authorization
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.Authorization: Bearer e5c3b842231543f.mGCUhfi0uI4J13k010V49D2GaBZ3j1E708X4a4396XNx48X3
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 are revocable, rotatable, scopeable keys which can be used during user registration, for data querying (including offloads fetching) and user deletion.
API Keys are generated on-demand with a name, scope, and expiry date and are disclosed to the creator only once. Please ensure the API Key is immediately stored somewhere secure.
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.Scope | Description |
USER_READ | |
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. |
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.
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.