API Key Format
Every request must include the x-api-key header.
curl https://whale-gateway.fly.dev/v1/stores/{storeId}/products \
-H "x-api-key: wk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"wk_live_...Production keys. Access real store data.
wk_test_...Sandbox keys. Isolated test environment.
Store Scoping
Each API key is bound to a single store. The {storeId} in the URL must match the store your key belongs to. Mismatches return a store_mismatch_error (403).
Scopes
API keys have scopes that control which resources they can access. Use the principle of least privilege — only grant the scopes your integration needs.
| Scope | Access |
|---|---|
| * | Full access (all read + write) |
| read:* | All read scopes |
| write:* | All write scopes |
| read:products / write:products | Product catalog |
| read:orders / write:orders | Order management |
| read:customers / write:customers | Customer profiles |
| read:inventory / write:inventory | Stock levels |
| read:locations | Store locations |
| read:analytics | Sales, traffic, and product analytics |
| read:storefront / write:storefront | Visitor sessions and events |
| read:agents / write:agents | AI agent configuration |
| write:agent | AI agent chat |
| read:cart / write:cart | Shopping carts |
| read:checkout / write:checkout | Checkout and payment intents |
| read:documents / write:documents | Document management |
| read:telemetry / write:telemetry | Error tracking and analytics events |
| read:portal / write:portal | Customer portal |
Auth Errors
401
authentication_errorMissing, invalid, or revoked API key.
403
permission_errorAPI key lacks the required scope for this endpoint.
403
store_mismatch_errorThe storeId in the URL does not match the API key's store.
Security Best Practices
- •Never expose API keys in client-side code, Git repos, or public URLs.
- •Use environment variables (
WHALETOOLS_API_KEY) to store keys. - •Create separate keys for each integration with minimal scopes.
- •Rotate keys periodically and revoke unused ones immediately.
- •Use
wk_test_keys during development — they cannot access production data.