Skip to main content

API Keys

Accessing Splashback APIs#

To access our APIs, you will use an API key. API keys are authentication tokens that do not expire until they are revoked, and are passed as an HTTP header:

Authorization: API-Key 00000000-0000-0000-0000-000000000000

API keys are generated using the Portal.

Scopes#

By limiting the scopes on an API key, you can determine what endpoints the key has access to. This is very useful for granting read-only keys to services whose only purpose is to ingest data. You should always choose the minimum scopes needed when provisioning an API key.

Below is a table of the different scopes and their permissions. Note that scopes are different to User Permissions and do not override them. For example, if your API Key has the write:data scope and you only have Viewer access to a Pool, you can still only read data in that Pool.

ScopePermissions
read:billingCan read billing information.
write:billingCan read and write billing information.
read:channelCan read channel data.
write:channelCan read and write channel data.
read:dataCan read pool data.
write:dataCan read and write pool data.
read:userCan read user data.
write:userCan read and write user data.

Best security practices#

warning

API keys have the potential to grant access to your entire Splashback account. As such, API keys should be treated with the same security measures as your password and any two-factor devices associated with your account.

  • Do not embed API keys directly in code. Use environment variables or configuration files that are not distributed or exposed publicly and read these values from your code instead.
  • Audit and delete unused or unsafe API keys. It is recommended that Tenant Owners audit the API keys of their users on a regular basis to determine if any users have created any unused or unsafe keys.
  • ALWAYS use the minimum scopes necessary for API keys. We can't iterate this one enough. Be extra careful with any write:* scopes and make sure that anyone who accesses this key is allowed to modify your Splashback data on your behalf.