Authentication
Every external read endpoint requires:
Authorization: Bearer whale_consumer_xxxThe key belongs to an application, not a person, and cannot be used to sign in to Portal. Whale derives the application identity from the key; clients must not submit or trust a consumer_id.
Key Practices
- Use separate keys for each environment and integration.
- Store keys in Key Vault, a secret manager, or protected environment variables.
- Never place a key in source code, browser code, images, or URL parameters.
- Rotate by issuing a new key, switching traffic, and then revoking the old key.
- Logs may contain the key prefix, never the full value.
| HTTP | code | Meaning | Action |
|---|---|---|---|
| 401 | unauthorized | Missing, invalid, expired, or revoked key | Stop retrying and inspect credentials |
| 403 | entitlement_denied | The application lacks the requested scope | Narrow the query or request a subscription change |
| 429 | rate_limit_exceeded | RPS, burst, or concurrency exceeded | Honor Retry-After and reduce concurrency |
| 429 | quota_exceeded | Daily quota exhausted | Wait for the UTC reset or request a quota change |