API keys and scopes
A shop holds up to 10 keys. The full key is shown once: Shoplio stores only a hash of it.
On this page
Create a key
- Open Developer in the dashboard, with the shop selected.
- Name the key and tick its scopes.
- Copy the key when it is shown. It is not shown again.
- Only the shop owner can create, change or delete keys.
- A key belongs to one shop. It can never reach another shop's data.
Send the key
Authorization: Bearer shp_0123456789abcdef0123456789abcdef
A key is shp_ followed by 32 hexadecimal characters. The dashboard later shows only its first 12 characters.
Scopes
Each endpoint needs one scope. A call without it answers 403 and names the scope, for example API key lacks the read_stock permission.
| Scope | Allows | On a new key |
|---|---|---|
read_products | Shop profile and product catalogue | On |
write_products | Create and update products and variants (no deletes) | On |
read_stock | List unsold stock, decrypted | On |
write_stock | Push new stock items | On |
edit_stock | Replace the content of an unsold item | Off |
delete_stock | Remove unsold items, singly or in bulk | Off |
read_orders | Orders (including decrypted delivered content) and customer accounts | On |
write_orders | Credit or debit store credit | On |
fulfill_orders | Deliver paid, pre-ordered or out-of-stock orders from your stock | Off |
read_analytics | Your crypto balance per gateway | On |
A new key gets seven scopes unless you change them. edit_stock, delete_stock and fulfill_orders stay off until you tick them.
Regenerate, edit or delete a key
- Regenerating a key issues a new secret. The old one stops working at once.
- Editing scopes changes what the key may do and keeps the secret.
- Deleting a key removes it for good.
When a key is refused
Every authentication failure answers the same 401. The API never says which cause it was.
{ "success": false, "error": "Invalid or missing API key" }- The
Authorizationheader is missing, or is notBearer shp_.... - No key matches: it was mistyped, deleted or regenerated.
- The shop is inactive.
- The owner's account is suspended.
- The owner is no longer on Pro or Enterprise.