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