Authentication
Send your key as a bearer token or as X-API-Key, and keep it off the browser.
Every call except /v1/status and /v1 needs a key. Keys start cdb_live_ and have 32 more characters.
Sending it
Send it as a bearer token:
Authorization: Bearer cdb_live_...
or, where a tool makes that awkward, as its own header:
X-API-Key: cdb_live_...
Both work on every endpoint. The key is never accepted in the address, because addresses end up in logs, browser history and anything a link is pasted into: a ?key= gets 400 bad_request.
Keeping it safe
We store only a hash of your key and its first 12 characters, so we cannot show it to you again: keep a copy when it is made. Call the API from your server rather than from a web page, where anyone could read the key from the page. If a key has leaked, revoke it; calls with a revoked key stop at once.
When it goes wrong
No key, a key we do not recognise and a revoked key all give 401 unauthorized, with a message saying which. See Errors for the rest.