API keys

The API Keys settings page lets you manage API keys for programmatic access to your data. Keys provide read-only access via the /api/v1 endpoints.

Getting there

• Where: Settings → API Keys.
• Permission: the api_keys resource.

Common tasks

Create a key

1. Select Create Key.
2. Give it a Name so you can identify it later (for example Production, Zapier, or Analytics).
3. Create it, then copy the key. Select Done when you've saved it somewhere safe.

Active keys show their name, a short prefix, and when they were created and last used. An empty list shows No API keys yet. Create one to get started.

What a key can read

A key reads what the staff member who created it can read, and nothing more. A key created by an Owner returns everything. Every endpoint lists the permission it needs on the API Documentation page.

Limited roles work differently depending on the endpoint, which is worth knowing before you debug a refusal:

• Locations and sessions narrow. Someone who can see only one location gets a key that returns just that location.
• Everything else is all or nothing. If their role does not grant that endpoint outright, the key is refused rather than given a partial list. Someone limited to one location does not get that location's customers, they get no customers.

This is checked on every request against that person's current role, so:

• Narrowing their role narrows every key they created, straight away.
• Deactivating them, or deleting their account, stops those keys working.

If a key stops returning data it used to return, check the role of whoever created it before assuming the key is broken. Create the key under someone with the access the integration needs, rather than widening a role to suit a key.

Revoke a key

Select Revoke on a key, then Confirm. Revoked keys move to a separate Revoked section and can no longer be used.

Tips

• Copy a new key right away, for security you may not be able to see the full value again later.
• Keys are read-only, so they're safe for analytics and reporting tools but can't change your data.
• Revoke any key you no longer recognise or use.
• Create a key under the person whose access the integration should have. Because a key follows its creator, a key created by someone who later leaves stops working when their account is deactivated, which is deliberate but will look like an outage to whatever was using it.