Create a key
1
Open Integrations and click New key
Give it a Name to recognize the key later, such as “Downtown store ERP”.
2
Choose the units
All units, including future ones, for the chain’s central system, or Selected units, to open only some shops to a partner.
3
Tick the permissions
They are the same as the team’s, with three differences: every key reads the units it reaches; Dispatch events spends credits like a dispatch made from the dashboard; Manage billing, through the API, only reads the balance and the statement (buying stays in the dashboard).
4
Set the token expiration, if you want
Token expiration: no expiration, 30, 90, 180 or 365 days. An expired token stops working until you issue another one.
5
Copy the token
When you click Create key, the Key token dialog shows the token only once. Use Copy token and store it in the system that will call the API before clicking Done.
Edit a key
Under View details, Edit changes the name, the units and the permissions. The token stays the same: the system doesn’t need an update.Rotate the token without downtime
A key can have two active tokens at the same time, so the rotation never leaves the system without access.1
Issue the new token
In the key’s details, Issue token. Copy it: it is also shown only once.
2
Update the system
Replace the token in the chain’s system and check that it keeps working.
3
Revoke the old one
In the Tokens table, Revoke token on the old token. Whoever still used it loses access right away.
Revoke a key
Revoke key turns off every token of the key right away. The key stays in the list as Revoked, for history, and cannot be reactivated: create another one.Last used shows the most recent call among the key’s active tokens. A revoked token’s use no longer counts, and a newly issued token only shows up after its first call.
Where the API shows in the dashboard
What the system does through the key appears in the dashboard with the API badge and the key’s name: in the author column of dispatches, in the credit statement and under Created by, in the item’s details. The credits spent are the same: 1 per person notified. Items created through the API carry the External reference (SKU), the item’s code in the chain’s system. You can also fill it in by hand, in the item form, so the system finds an item you registered in the dashboard.API documentation
For whoever will build the integration: authentication, first request and the reference of every endpoint.