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 create:data scope and you only have Viewer access to a Pool, you can still only read data in that Pool.

ScopePermissions
read:dataCan read pool data.
create:dataCan create pool data.
update:dataCan modify pool data.
delete:dataCan delete pool data.
read:userCan read user data.
create:userCan create user data.
update:userCan modify user data.
delete:userCan delete 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 create:*, update:* and delete:* scopes by ensuring that anyone who accesses this key is allowed to modify your Splashback data on your behalf.