API keys and permissions
Every request needs an API key, sent as a bearer token:
Authorization: Bearer k_live_...
Creating and revoking keys
Keys are managed in the Seamless backoffice under Settings, System Settings, API keys.
A key is shown once, when you create it. If you lose it, revoke it and create another. Revoking a key stops it working straight away.
It is worth creating a separate key for each system you connect, so that you can revoke one without disturbing the others.
What a key can read
Two things limit a key, and you choose both when you create it: the sites it covers and its permissions.
Sites
A key reads only the sites you pick for it, and only sites that you have access to yourself. If your own access to a site is removed, your keys stop reading that site too.
You can change which sites a key covers later.
Permissions
| Permission | In the backoffice | Lets the key read |
|---|---|---|
read:products | Product library | categories, products, modifierGroups |
read:reports | Sales data | orders, refunds, dailySummary |
read:costs | Cost prices and profit | costPrice on product prices |
read:staff | Staff | Staff names on orders, order lines and refunds |
Permissions are fixed when the key is created. To change them, create a new key.
Asking for a field the key has no permission for returns a FORBIDDEN error that names the missing permission. Fields you do not ask for are never checked, so a key without read:staff can still read orders as long as the query leaves the staff fields out.
Keeping keys safe
Call the API from your server. A key in a browser or a mobile app can be read by anyone who uses it.
Keep keys out of source control as well, in an environment variable or a secrets manager, and give each key only the sites and permissions it needs. If a key may have leaked, revoke it: there is no cost to creating a new one.