Skip to content

Authentication

There are two ways to authenticate with our API:

  • JWT bearer authentication through the WebApp
  • API key authentication

This page focuses on API key authentication.

Required Request Headers

To authenticate with the API, we require the 'X-Account-Id' and 'X-API-Key' headers to be present on any HTTP request.

X-Account-Id

Your Account Id can be found on the account settings page.

Ensure your Account Id is present as a 'X-Account-Id' request header

X-API-Key

Api keys can be created through the account settings, API or CLI toolkit.

Ensure your API key is present as a 'X-API-Key' request header

API keys

You are able to create and manage as many fine grained API keys as you wish, though do be careful to keep them safe since they can do damage if they get into the wrong hands. The best practice is to create api keys with the minimum permissions required to get the job done. You can achieve this by configuring these settings when creating an API key.

  • expires_at - unix timestamp when the key will expire
  • is_admin - whether or not the API key belongs to an admin
  • all_set_operations - should the API key be used to read or write from all sets within your account
  • permissions - fine grained permissions for specific sets / tags.

is_admin

A user can call any endpoint through the API except from account operations, which can only be performed through the webapp.

all_set_operations

  • Undefined - this property will be ignored
  • Read - allow the API key to query for any data points / analytics within any of your sets
  • Write allow the API key to write data into any set

permissions

Each fine grained permission has the following properties:

  • set_id - the set which the rule applies to
  • tags - a list of tags which the rule applies to
  • all_tags - apply the rule to all tags within the set
  • operations - allow the API key to perform read / write operations

Notes

  • api keys / permissions cannot be modified once they have been created
  • api keys can be temporarily disabled / enabled
  • api keys can be deleted
  • deleting / disabling / enabling an api key may take up to 5 minutes to take effect

When an API key is generated make sure to keep it safe as we don't store them ourselves.