Authentication & API keys
Key types, roles, and per-key permission scopes for the Foundry APIs.
Key types
Every API request authenticates with a bearer token: Authorization: Bearer <key>.
| Key | Surface | Created via |
|---|---|---|
fims_* (admin) | Partner API — the full back-office surface | Settings → API Keys → Create, key type Admin |
fims_sf_* (storefront) | Storefront API only — safe to use from a browser | Settings → API Keys → Create, key type Storefront, bound to one headless channel |
Admin keys are rejected on the storefront surface and vice versa. Keys are stored hashed — the plaintext is shown exactly once at creation. Keys can be revoked at any time and can carry an expiry date.
- 401 — missing/malformed header, or an invalid, revoked, or expired key.
- 403 — valid key, but it lacks the permission the endpoint requires.
Permissions
Admin access is gated by fine-grained permission strings; each Partner API endpoint declares the one it needs (shown per-endpoint in the API explorer).
- Products & catalog:
products.read/products.write,variants.read/variants.write - Inventory & warehouses:
warehouses.read/warehouses.manage,stock.adjust,stock.count - Suppliers:
sources.read/sources.write - Sales channels:
channels.read/channels.write - Orders:
orders.read/orders.write - Purchase orders:
pos.read/pos.write/pos.receive - Invoices & costs:
invoices.read/invoices.write/invoices.approve,landed_costs.read/landed_costs.write - Shipments:
shipments.read/shipments.manage - Reports:
reports.read - Admin:
webhooks.manage,apikeys.manage,users.manage,settings.read/settings.write,audit.read,export.run, and more
Owner-only permissions (closing the organization, data recovery) can never be assigned to an API key.
Roles
A role is a named permission bundle. When you create a key you pick a role as its starting point:
| Role | Intended for |
|---|---|
| ADMIN | Full access (minus owner-only permissions) |
| CATALOG_MANAGER | Product/catalog read-write, channel and supplier management |
| CHANNEL_MANAGER | Sales channels, orders, listings |
| PURCHASING | Suppliers, purchase orders, invoices, costs |
| WAREHOUSE | Stock adjustments, counts, receiving |
| FULFILLMENT | Orders and shipments |
| FINANCE | Invoices, landed costs, reporting, audit |
| CUSTOMER_SERVICE | Order lookup and edits, read access around them |
| VIEWER | Read-only across the catalog, orders, and purchasing |
Per-key scopes (least privilege)
A key can carry explicit scopes that override its role — so you can mint a key that does exactly one thing without inventing a new role:
- Scopes empty → the key gets its role’s permissions.
- Scopes set → those scopes are the key’s exact permissions; the role remains as a display label.
Two rules at creation: every scope must be assignable (owner-only permissions are excluded), and you can’t grant a scope you don’t hold yourself.
curl -X POST https://api.foundryims.com/api/v1/api-keys \
-H "Authorization: Bearer <your-admin-key>" \
-H "Content-Type: application/json" \
-d '{
"name": "Accounting sync — read-only",
"role": "FINANCE",
"scopes": ["invoices.read", "pos.read", "orders.read"]
}'The resulting key can read invoices, purchase orders, and orders — and nothing else. Calls to any other endpoint return 403.
Key management endpoints
All require the apikeys.manage permission.
| Method & path | Purpose |
|---|---|
GET /api-keys | List active keys (name, prefix, role, scopes, last used, expiry) |
GET /api-keys/permissions | The permission catalog: assignable permissions, what you may grant, and per-role presets |
POST /api-keys | Create an admin key — { name, role?, scopes?, expiresAt? }. Returns the plaintext key once |
POST /api-keys/storefront | Create a storefront key bound to a headless channel — { name, channelId, expiresAt? } |
DELETE /api-keys/:id | Revoke a key immediately |
Rate limits
Admin keys are limited to 300 requests/min per key. See the Partner API reference for headers and the 429 response shape; storefront keys have their own per-channel limits documented in the Storefront API reference.