Authentication and scopes
How API keys work, what each scope allows, and how to keep keys safe.
Send your API key in the Authorization header of every request:
Authorization: Bearer fom_live_3f9a1c2b7d4e_Xk2…A key belongs to one shop, so you never send a shop id. Requests without a working key get 401 UNAUTHORIZED.
A key acts for the person who made it
Everything a key does is done as the Owner or Manager who made it, limited to the key's scopes. A request needs both:
- the scope on the key, and
- the permission for its creator in the shop today.
If that person leaves the shop or loses the permission, their keys stop working and show Not working in Settings. Make a new key from someone who still has access.
Scopes
Tick only what a tool needs when you make the key. You can only give scopes for things you can do yourself.
| Scope | Allows |
|---|---|
orders:read | See orders |
orders:write | Create orders and change their status |
customers:read | See customers |
customers:write | Add and change customers |
products:read | See products and stock |
products:write | Add and change products |
stock:write | Change stock |
deliveries:read | See deliveries |
deliveries:write | Change deliveries |
GET /shop works with any key and shows its scopes. A missing scope gets 403 FORBIDDEN.
Keep keys safe
- Shown once. FOM stores only a hash of the key. If you lose it, make a new one.
- Server only. Never put a key in a website, a mobile app or a public repository; anyone with it can act as you.
- Limit where it's used. When making a key you can set an expiry date and allowed IP addresses (single addresses or ranges like
203.0.113.0/24). Requests from other addresses get403. - Revoke a key in Settings → Developers the moment it may have leaked. Programs using it stop at once. Keys start with
fom_live_, so they are easy to spot in logs and code scanning.
API access
Keys only work while your shop has the API access add-on. Without it, requests get 403 with a message saying so. Keys made earlier start working again when the add-on is back.