Skip to content
Calcadian logoCalcadian

API keys

A key identifies the account that pays for the call. Treat it like a password.

Key creation is disabled during prelaunch. Everything described here is implemented and will be open when the API launches.

Format

Keys look like cal_live_ or cal_test_ followed by 43 URL-safe characters derived from 32 random bytes. Only a SHA-256 hash and a short display prefix are stored, so nobody, including Calcadian, can recover the plaintext later.

Shown once

The full key is returned exactly once, at creation. Copy it into your secret store immediately. If you lose it, create a new key and revoke the old one.

Storage

  • Keep keys in environment variables or a managed secret store.
  • Never commit a key, never paste one into a client-side bundle, a URL or a support ticket.
  • Use a separate key per application so you can revoke one without breaking the rest.

Rotation

  1. Create the replacement key.
  2. Deploy it everywhere and confirm traffic is flowing on the new prefix.
  3. Revoke the old key.

Multiple active keys on one account are supported precisely so rotation needs no downtime. All keys on an account share the same monthly quota.

Revocation

Revoking is immediate. The next request on that key returns 401 REVOKED_API_KEY. Revoke as soon as a key is exposed; do not wait for a rotation window.

Keys are managed in your account. See also Authentication.