The Sentiance Backend speaks REST and GraphQL, and share the same authentication mechanism.

An authorization header with content Bearer <token> authenticates and authorizes your request. Based on what kind of token is supplied, the level of access is determined and could affect the functionality of various calls.

Example:

Authorization: Bearer e5c3b842284045d98ed042814f31543f

The User Token

To understand the usage of a User Token, let us first talk about the the two types of Users the platform supports: SDKUser and ControlUser.

SDKUser

SDKUsers are created when the SDK initializes with an App ID and App Secret. They only have a userID and are only authenticated by their token. You can retrieve this token from an initialized SDK.

ControlUsers

ControlUsers are created when you sign up via Journeys or Insights. They have an email/password pair that can be used to get a token. See below.​

User Tokens identify one unique user and can be used to retrieve any data belonging only to that user.

Common use-cases of this token included getting user timeline, retrieving segments, retrieving predictions, etc. to create a unique UI for the user to view their own data.

The Server Token (Deprecated)

Server Tokens provide you access to all the user data under one application. As such they should only be used in server-side integrations and should never be transmitted to end-user devices.

You can retrieve the Server Token by visiting apps page on Insights, if you have Developer access.

Common use-cases of this token include building internal dashboards to view within your team, run batch processes on users, etc.

API Keys

To remedy the shortcomings of our legacy Server Tokens we introduce API Keys: a revocable, rotatable, scopeable key with which to query the API.

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.

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 3 different scopes: user.read, user.delete and user.link. We strongly suggest that you use multiple API Keys with limited scopes for different operations.

Self-Expiring

For increased security, API Keys are self-expiring. The expiry time is 1 year (recently changed from 90 days) from 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.

Manage Your Own API Keys

You can manage your own API Keys from our developer portal. Our developer portal has all the tools you need, including a full history of API Keys created, revoked or expired. See it in action here.​

Most of our clients are based on our European platform (even US and Australian clients) at https://insights.sentiance.com. If you are using our US-based or Australian-based platform, please use respectively https://insights.d4.sentiance.com and https://insights.e6.sentiance.com.

Authenticating With a Control User

If you've signed up via the Insights dashboard or Journeys, you have a ControlUser to play around with. You can use the following steps to get a token for your user using your email/password pair. The token can then be used to call all GQL and REST endpoints.

This involves two steps:

• ​Pass in email/password to get a short-lived (< 10 mins), Authorization Code.

• ​Exchange Authorization Code for Authentication Token.​

Note that neither step is optional. You can't make any calls with the Authorization Code apart from exchanging it for the Authentication Token which you can then use for other API calls.

{
    "user": "5ca289e00000000000000000",
    "authorization_code": "277378a4aa719a24d173e4d71d5f962561c95b9e67a0eee79f5f85b699422165f66d989ebf2fb195f4b7de026663aa8743d04b34fb313c33138c"
}

{
    "id": "8ccbed3b-87b2-a71f-05f680ccb1dd",
    "user_id": "5a97cc743992560500000008",
    "token": "e2580b3dfd7c8a36d10e61a82a3ff7d3c198a22d9c7aabe44774847ba566ef02083e861632ca913b3990293eeb0c4779194c304c9982786470b08",
    "refresh_token": "506fe2ee2217d263bea480ad9a0711f3f4febbcf04ae86025bddabd0de008df65020bfeb24c4a0974668ad33729b0cc3bb0053de",
    "expires_at": "2019-04-02T13:22:22.508Z",
    "token_type": "self",
    "updated_at": "2019-04-02T09:22:22.508Z",
    "created_at": "2019-04-02T09:22:22.508Z",
    "app_id": "00000000000000000000000a"
}

Your token may expire after an unspecified period of time. When that happens you can use the refresh token received in the previous API call to get a new Authentication Token.

{
    "id": "8ccbed3b-87b2-a71f-05f680ccb1dd",
    "user_id": "5a97cc743992560500000008",
    "token": "e2580b3dfd7c8a36d10e61a82a3ff7d3c198a22d9c7aabe44774847ba566ef02083e861632ca913b3990293eeb0c4779194c304c9982786470b08",
    "refresh_token": "506fe2ee2217d263bea480ad9a0711f3f4febbcf04ae86025bddabd0de008df65020bfeb24c4a0974668ad33729b0cc3bb0053de",
    "expires_at": "2019-04-02T13:22:22.508Z",
    "token_type": "self",
    "updated_at": "2019-04-02T09:22:22.508Z",
    "created_at": "2019-04-02T09:22:22.508Z",
    "app_id": "00000000000000000000000a"
}