Authentication

Preferred header

Authorization: Bearer cal_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

An x-api-key: <key> header is also accepted for clients that cannot set an Authorization header. Both are equivalent.

Never put a key in a URL

Query strings are recorded in server logs, proxy logs and browser history. A request that carries ?api_key= is rejected with 401 API_KEY_IN_QUERY_STRING even when the key itself is valid. Treat any key sent that way as compromised and revoke it.

Environments

• cal_test_ keys work only against the sandbox deployment.
• cal_live_ keys work only against the live deployment.

Presenting a key from the wrong environment returns 403 ENVIRONMENT_MISMATCH. The environment is readable from the key itself, so a sandbox key can never be mistaken for a live one.

Authorization is resolved live

Plan, quota and feature access are resolved from the owning account on every request, not from the key. An upgrade, downgrade or cancellation takes effect on the very next call.

Failure codes

• 401 MISSING_API_KEY: no key was presented.
• 401 INVALID_API_KEY: unrecognised key.
• 401 REVOKED_API_KEY: the key was revoked.
• 401 EXPIRED_API_KEY: the key passed its expiry date.
• 403 ENVIRONMENT_MISMATCH: right key, wrong environment.

Manage keys on the API keys page.