Skip to content


Most API calls require to be authenticated.

Auth Token

This authentication scheme uses a simple token-based HTTP Authentication scheme. Token authentication is appropriate for API client setups, such as scripts.

The token is associated to a specific User and a specific App.

For clients to authenticate, the auth token key should be included in the Authorization HTTP header.

The key should be prefixed by the string literal "Token", with whitespace separating the two strings.

For example:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Contextual Dashboard Settings

To get the "Contextual Auth Token" go to the Contextual Dashboard Settings and choose from the API Tab

Contextual Dashboard Settings

Install Token Authentication

Install Token Authentication is a mechanism by which devices an authenticate with the server without the need for a permanent preshared key.

How it works:

  1. Dashboard User generates an token from GET /v3/users/token?installid=xxxxxxx
  2. The token is then sent to the device using whatever means available (deeplink, simple copy paste from slack, push, sms). See section on token distribution
  3. The device then uses the intall token in the request header to make authenticated requests.

Tokens by default have a expiry of one hour

Endpoints currently supporting install token v3/tooltips

Token Distribution

This is the mechanism by which an install auth token is sent to the device install for which the token is generated. The token is just a simple string it can be distributed to the device using any means by which a string can be published. Deeplink: a deeplink is genererated which is sent to the device through a qr code,push or sms. When the user clicks on the deeplink it willl launch the app and the token will be stored by the app Through slack, this is mostly for testing, the developer can copy the plain token into his slack, and receive it in the device and paste in to the sample app’s text field for entering the token (sdk developers note this text field needs to be provided)

Example :

  1. Get token http://localhost/v3/users/token/?app_key=demo2278440&installid=c12b156b-8592-4545-989b-4468a3936983
  2. Use token in query param or header http://localhost/v3/tooltips?installid=c12b156b-8592-4545-989b-4468a3936983&token=52b29f04992fe340912d273be198f533159f0368

Last update: 2023-04-12