Key securityStart
Treat your keys as secrets. We store a SHA-256 hash, plus the prefix and last four characters so you can tell keys apart.
Limit what a key can do
| Control | Effect | Limits |
|---|---|---|
| Scopes | Only the listed services answer to the key. | models, search, maps, mail |
| IP allow-list | Calls from other addresses get 403 ip_not_allowed. | Up to 32 IPs or CIDR ranges. IPv4 /8 or narrower, IPv6 /16 or narrower. An IPv6 caller also matches by its /64. |
| Monthly budget | A call that would take the key past its budget this month (UTC) gets 402 key_budget_exceeded. Open holds count. | $1 to $1,000,000 |
| Expiry | The key stops working after the set number of days. | 1 to 730 days, set when you create it |
| Active keys | Revoke a key to make room for another. | Free 3, Starter 10, Build 25, Scale 50, Pro 100 |
You can change a key's name, scopes, allow-list and budget later. Expiry is fixed at creation.
Rotate a key
To replace a key while your app keeps running:
- Create a new key with the same scopes and limits.
- Deploy it, and check in the key list that the old key's last use stops moving.
- Revoke the old key. Revocation takes effect within seconds.
Keep keys on your server
Call the API from your backend. /v1 answers cross-origin requests, but a key that ships to a browser is public. A Free tier key used from more than 3 networks in an hour is refused with 429 key_shared; on paid tiers that pattern is flagged for review.
Understand edge checks
An edge gateway checks every /v1 call before it reaches the API: the key, its scope and a per-key ceiling of 12,000 requests a minute (bursts up to 2000). Invalid keys from one address are slowed to about 30 lookups a minute (per /64 for IPv6), then refused with 429 rate_limit_exceeded.