Authentication with an API key

Send your key on every request:

Authorization: Bearer ceco_live_2f3a9c1e0b7d4a6f8e21_Q7v…

The key format

A key looks like ceco_live_<id>_<secret>.

• ceco_live or ceco_test says which kind it is. Both reach the same account and data; a test key exists so that one pasted into the wrong place is recognisably the wrong kind.
• <id> is public. It appears in your key list, so you can match a key to the system using it.
• <secret> is 256 random bits. CECO stores only a SHA-256 of it, so the full key is shown once, when it is minted, and never again. Nobody at CECO can show it to you later.

Keys are minted by a person signed in to a Business account, on the account page under API. A key cannot mint, list or revoke keys, so a leaked key cannot make more of itself.

Storing a key

Treat it like a password to your account's documents:

• keep it in your platform's secret store or an environment variable, never in source code;
• give each system its own key, named for what it does, so one can be revoked alone;
• if a key may have leaked, revoke it at once. Your key list shows the countries each key has been used from, which is often how a leak is noticed.

Rotating a key

Two steps, with no downtime:

1. Mint the new key and deploy it where the old one was.
2. Revoke the old key once nothing uses it. The key list shows when each was last used.

Both keys work in between.

When a key stops working

• Its lifetime ends. Every key is minted with one: 7 days, 30 days (the default), 90 days, or never.
• You revoke it. Revocation takes effect on the very next request; there is no cache anywhere that keeps a revoked key working.
• Your Business plan ends. Every key of the account is revoked permanently, even a key minted to never expire. Renewing later does not bring the keys back: you mint new ones. While a payment is failing the keys keep working until the end of the period already paid for, and the account page warns you of the date.

A key that no longer works answers 401 invalid_api_key, whatever the reason. The reason is shown to you in your key list, never to whoever is holding the key.

Limits

Each key may make 120 requests a minute, in bursts of up to 30 at once. Every response to a key carries X-RateLimit-Limit (requests a minute), X-RateLimit-Remaining (requests you can send now) and X-RateLimit-Reset (seconds until the allowance is full again). Past the limit the answer is 429 too_many_requests with a Retry-After in seconds.