API keys and permissions
Give each system its own key with only what it needs.
Overview
An API key belongs to your company and carries a set of permissions. It can also be limited to some warehouses or to one 3PL client.
Before you begin
- You are an admin, or your role includes See and manage API keys, API logs and webhooks.
Make a key
- 1Open Settings → API and Webhooks → API keys and click New key.
- 2Enter a Name, and optionally an expiry date in Expires on.
- 3Tick what the key may do under What this key may do. You can only give a key what your own role allows.
- 4Optionally tick Warehouses to limit it. Ticking none means all warehouses.
- 5Copy the access key and the secret key.
Permissions
Permission is the value a 403 answer gives in requiredPermission. See Errors.
| On the settings page | Permission | Lets the key call |
|---|---|---|
| Read stock, movements, warehouses and shipments | stock:read | GET /stock, /stock/{sku}, /warehouses, /movements, /shipments |
| Read orders | orders:read | GET /orders, /orders/{id} |
| Create and cancel orders | orders:write | POST /orders, /orders/{id}/cancel |
| Create goods receipts | inbound:receive | POST /goods-receipts |
| Create stock adjustments | stock:adjust | POST /adjustments |
Limit a key to some warehouses
A key limited to some warehouses sees and changes only those. This applies to stock, warehouses, movements, shipments, adjustments and goods receipts.
Good to know Orders are not limited by warehouse: a key with orders:read reads all of the company's orders.
Keys for 3PL clients
If you run a warehouse for other brands, a key can belong to one client. Choose the client under For a client (3PL). Such a key:
- Reads only that client's stock, movements, orders and shipments.
- Can place orders for that client's items.
- Cannot create goods receipts or stock adjustments.
Manage keys
| Action | What happens |
|---|---|
| Show | The eye beside the secret key shows it again, if your role covers everything the key may do. |
| Revoke | The key stops working and its secret is erased. This cannot be undone. |
| Delete | Removes a revoked key and its request log lines. A key must be revoked first. |
A company can have 20 active keys. Use one key per system: when something goes wrong you can see which system it was, and revoke one without stopping the others.