Authentication & API Keys
Bearer keys issued per integration by the shop; revocation is immediate; secrets are never retrievable.
Every request carries an API key as a bearer token:
GET /v1/customers HTTP/1.1
Host: api.shopcommander.com
Authorization: Bearer sc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Keys start with sc_live_. Only a SHA-256 hash is stored; the plaintext is shown to the shop once when the key is issued and cannot be recovered. The API never uses cookies or sessions and never accepts a key in the query string.
Integrations, keys, and shops
- An integration is the principal: it belongs to exactly one shop, holds a set of scopes, and owns its keys and webhook endpoints.
- A key is a credential for its integration. An integration can hold two active keys so a rotation can overlap: issue the new key, switch your caller, revoke the old one.
- Keys share their integration's rate limit; integrations share the shop's ceiling. Creating more keys never buys more throughput.
- One key reaches one shop. A vendor serving many shops holds one key per shop, granted by each shop.
Revocation
Revoking a key or an integration takes effect on the next request — authority is the database row, not a cached token. A revoked key returns 401 authentication / invalid_api_key; a suspended integration returns 403 permission / integration_suspended.
Authentication errors
| Status | code |
Meaning |
|---|---|---|
| 401 | missing_api_key |
No Authorization: Bearer header |
| 401 | invalid_api_key |
Unknown, malformed, or revoked key |
| 403 | integration_suspended |
Platform operators suspended the integration (reason shown to the shop) |
| 403 | shop_inactive |
The shop's Shop Commander account is inactive |
| 403 | insufficient_scope |
Valid key, but the integration lacks the scope — details.required_scope names it |
| 503 | public_api_disabled / public_api_writes_disabled |
A platform kill switch is on; retry later |
All errors use the error envelope.
Keep keys safe
- Store keys in a secrets manager or environment variable, never in source control or a browser bundle.
- Use one integration per system so a compromise is contained and the shop can see, in its activity log, which system did what.
- If a key leaks: the shop revokes it in Settings → Developer, issues a replacement, and reviews the integration's activity and the audit history. Every change made through the API is attributed to the integration by name in the shop's audit trail.