---
title: Authentication
description: Application API key usage, rotation, and authentication errors.
---

# Authentication

Every external read endpoint requires:

```http
Authorization: Bearer whale_consumer_xxx
```

The 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 |