API Keys
Create, rotate, and revoke CanalAPI API keys, plus per-key IP allowlist, model allowlist, quota, and expiration.
API keys authenticate every request to CanalAPI. Each key belongs to a single account but can be configured with its own access scope, quota, and expiration so you can hand out keys to different applications and environments safely.
Create a key
- Open the console and go to API Keys.
- Click Create new key.
- Set a recognizable name (include purpose / environment, e.g.
web-frontend-prod). - Configure the access scope and quota as needed (see below).
- Click Create.
Copy the key immediately — the full secret is shown only once and cannot be recovered after the dialog closes. The server stores only a hash of the key.
Access scope and quota
Each key can be configured independently at creation time or later:
| Control | Purpose |
|---|---|
| Model allowlist | Only allow calls to listed models; everything else returns 403 Forbidden |
| IP allowlist | Restrict callers by IP / CIDR; out-of-range requests return 403 |
| Quota cap | Total USD this key may spend; once reached, the key is paused (account balance is unaffected) |
| Expiration | Auto-expires the key after the configured date |
| Status | Enabled / disabled (disabled keys reject auth immediately but keep their metadata) |
These controls are key-level. Account-wide quotas and subscription quotas are aggregated at the account level — see Subscriptions and Rate Limits.
Typical configurations
| Scenario | Suggested settings |
|---|---|
| Production web service | Model allowlist: just the 1–3 models you use; IP allowlist: server egress IPs; no expiration |
| CI job | Quota cap: enough for a month of builds; expiration: 6 months; IP allowlist: CI runner IPs |
| Temporary local debugging | Quota cap: low (e.g. $5); expiration: 30 days |
| Partner integration | Strict model and IP allowlists; quota cap per contract |
Edit / rotate / revoke
Edit
Click a key in the API Keys list to open its detail page, where you can edit the name, access scope, and quota. The already-consumed quota cannot be reset; create a new key if you need a fresh allowance.
Rotate
Rotate keys periodically, or immediately whenever a key may have been exposed:
- Create a new key (mirror the old key's access scope).
- Update your application to use the new key.
- Confirm migration via Usage Logs.
- Revoke the old key.
Revoke
Click Revoke in the API Keys list and confirm. The key is invalidated immediately and requests using it return 401 Unauthorized. Revocation is irreversible — make sure your application has switched first.
List view
The API Keys list shows:
- Key name and last 4 characters (never the full plaintext)
- Status: enabled / disabled / expired / revoked
- Cumulative spend vs. quota cap
- Created time, last-used time
- Whether model / IP allowlists are applied
Best practices
- One purpose per key. Use separate keys per service, environment, or CI job — revocation and billing attribution become surgical.
- Server-side only. Never embed a key in browser JavaScript or a mobile app. Use a backend proxy.
- Combine with a quota cap. Even if a key leaks, the cap limits the damage.
- Combine with an IP allowlist. When your server egress is fixed, IP allowlisting is the strongest layer of defense.
- Use secret managers. Inject the key via Vercel / Railway env vars, AWS Secrets Manager, Doppler, etc. — never check it in.
- Monitor usage. Check Usage Logs regularly for unexpected spikes.
If a key is leaked, revoke immediately, then review the relevant time range in Usage Logs for suspicious activity. If unauthorized charges occurred, raise a ticket via Support.