Skip to main content

Authentication

Every API request is authenticated with a bearer key:

Authorization: Bearer ck_your_key_here

Requests without a valid key are rejected with 401 Unauthorized. See Errors.

Keys​

Keys belong to an activated workspace. A workspace that has not been activated holds no keys and cannot create any; the Console points you at Billing instead. When the workspace is activated, every member of it, including anyone invited before activation, gets a private key named Default. Open API keys in the Customer Console to reveal yours or create additional keys.

  • Keys start with ck_. Add this prefix to your secret-scanning rules.
  • The full key is shown when created and can be revealed later by its owner. Treat the key as a secret.
  • Keys authenticate the workspace, but each key has an owner. A key you create is private to you by default; teammates don't see it, so your organization can tell who is using the API. Workspace admins and organization owners/admins can create a workspace-shared key that every member sees and can use, and only they can rename, rotate, or revoke it. Prefer private keys: use a shared key only when a service genuinely needs a workspace-owned credential, since sharing loses per-person visibility and a departure forces a rotation that disrupts everyone. Either way, all usage draws on the workspace's shared credit balance and there are no per-key limits.
  • Label your keys. One key per app or environment (prod-backend, staging, cli-tools) simplifies rotation and incident response.

Rotating and revoking​

From the Console you can:

  • Rotate a key. The Console mints a replacement and revokes the old key in one step. Update your deployment with the new value.
  • Revoke a key. It stops working and cannot be recovered.

Creating, rotating, and revoking keys can take up to one minute to take effect. During that interval, an old key may still work and a new key may not work yet.

For a planned, zero-downtime change, create a second key, verify it, update the deployment, and then revoke the old key. If a key may be compromised, rotate or revoke it immediately and account for the one-minute change window.

Handling keys well​

  • Keep keys server-side where you can. Load them from environment variables or your secret manager, never from source control.
  • Calling from a browser is supported. A key embedded in a public web page can be read and reused by anyone. For public applications, proxy Celeris calls through your backend. See Making requests.
  • Prefer private keys. Give each person and each app its own unshared key so usage stays attributable. Use a workspace-shared key only when the application requires a credential shared by the workspace.
  • Rotate on departure. Rotate shared keys when someone with production access leaves your team, and revoke or rotate any keys the departing person created.