Authentication and Authorization

The Sentiance Backend speaks REST and GraphQL, and the authentication mechanisms for both of these are the same.

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 App Token

App 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 app 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.

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:

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

post
Email/Password --> Authorization Code

https://api.sentiance.com/auth/local
Pass in the email/user pair for a short-lived Authorization Code.
Request
Response
Headers
Content-Type
required
string
application/json
Body Parameters
username
required
string
The email you signed up with.
password
required
string
Your password.
200: OK
{
"user": "5ca289e00000000000000000",
"authorization_code": "277378a4aa719a24d173e4d71d5f962561c95b9e67a0eee79f5f85b699422165f66d989ebf2fb195f4b7de026663aa8743d04b34fb313c33138c"
}

post
Authorization Code --> Authentication Token

https://api.sentiance.com/auth/token
Exchange authorization code for a longer-lived Authentication Token.
Request
Response
Headers
Content-Type
required
string
application/json
Body Parameters
grant_type
required
string
Set this to "code".
code
required
string
Place here the authorization code retrieved in the previous call.
token_type
required
string
Set this to "self".
200: OK
You will get back a short-lived token authentication token and a refresh token. The refresh token can be used to retrieve 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"
}

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.

post
Token Refresh

https://api.sentiance.com/auth/token
Used to refresh an authentication token. You may have noticed this is same endpoint as the Code Exchange, but the grant_type has a different value.
Request
Response
Headers
Content-Type
required
string
application/json
Body Parameters
grant_type
required
string
Set this to "refresh_token"
refresh_token
required
string
Set here the refresh token received during a Code Exchange or a previous Token Refresh call.
200: OK
This will return a new auth token/refresh token pair.
{
"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"
}