Authentication
API keys, scopes, and security best practices.
API Keys
Every request to the Whatalo API must include an API key in the X-API-Key header.
curl https://api.whatalo.com/v1/products \
-H "X-API-Key: wk_live_abc123..."Key Formats
| Prefix | Environment | Usage |
|---|---|---|
wk_live_ | Production | Real store data, full rate limits |
wk_test_ | Test | Same data, lower rate limits |
Creating Keys
API keys are created from the store dashboard at Settings > Developer > API Keys. Each key is assigned specific scopes that control what it can access.
API keys are shown only once at creation time. Store them in a secure secrets manager — never hardcode them in source code.
Scopes
Scopes define what resources an API key can access. Use the minimum scopes required for your integration.
| Scope | Access |
|---|---|
read:products | List and read products, variants |
write:products | Create, update, delete products |
read:orders | List and read orders |
write:orders | Update order status |
read:customers | List and read customers |
write:customers | Create and update customers |
read:store | Read store information |
read:categories | List and read categories |
write:categories | Create, update, delete categories |
read:discounts | List and read discounts |
write:discounts | Create, update, delete discounts |
read:webhooks | List webhook endpoints |
write:webhooks | Create, update, delete webhooks |
Security Best Practices
- Never expose keys in client-side code — API keys should only be used server-side
- Use test keys for development — switch to live keys only in production
- Rotate keys periodically — revoke unused keys
- Use minimum scopes — request only the scopes your integration needs
- Monitor usage — check the Developer Dashboard for unusual activity
OAuth 2.1
For integrations that act on behalf of merchants (third-party apps, MCP clients, multi-tenant SaaS integrations), Whatalo provides a complete OAuth 2.1 Authorization Server with Dynamic Client Registration, mandatory PKCE, refresh token rotation, introspection, and revocation.
The full OAuth documentation is in its own section: OAuth 2.1 →