API keys and personal tokens

Use an API key for application requests and a personal token for work you perform as a person. Both use Authorization: Bearer when calling the HTTP API.

For browser access, mint a stream token on your server after checking that the user may read the session. Keep API keys and personal tokens out of browser code.

API keys

Create a setup key with the scopes needed to register providers and agents. A running app using the direct API client against existing agents usually needs read,data. Declarative SDK agents also need control to register definitions during initialization.

const { plaintext } = await client.apiKeys.create({
  key: { name: "support-app", scopes: ["read", "data"] }
})
// Save plaintext in your app's secret configuration. It is returned only once.

Creating a key requires control scope. The new key belongs to the environment in which it is created. Select the environment in the console before creating a key, or use an existing key for that environment with apiKeys.create.

Set CEREAL_API_KEY separately in each deployment: a development key for development, a production key for production. The SDK learns the target from the credential; no environment selector is required. If you supply x-cereal-environment, it must match the key's environment slug or ID. A mismatch returns Forbidden with reason: "environment_mismatch". A header cannot grant access to another environment.

You can restrict a key by operation, agent, asserted identity, expiry, and spend. Restrictions narrow its scopes; they cannot grant a missing permission. An empty operation or agent list means unrestricted. See the API key reference for all fields and identity for identityScopes.

await client.apiKeys.list()
await client.apiKeys.revoke({ id: keyId })
await client.me() // Inspect the credential and selected environment.

Scopes

Scopes are independent: control does not include read or data.

Each API operation lists its required scope. A missing scope returns Forbidden. A missing, revoked, or expired credential returns Unauthorized.

Personal tokens, and npx @trycereal/cli login

npx @trycereal/cli login
npx @trycereal/cli logout

login opens the console to approve the CLI and saves a personal token to ~/.config/cereal/credentials.json. logout removes the saved token and revokes it. Personal tokens act as you; they are distinct from environment-bound application keys. Manage tokens in Settings → Profile.

CLI commands select credentials in this order: --api-key, CEREAL_API_KEY, then the saved login. An environment variable therefore takes precedence over your personal login. The TypeScript client does not load the CLI credential file; pass its credential or set CEREAL_API_KEY in the application process.

For HTTP requests with a personal token, use x-cereal-organization and x-cereal-environment to select the target. Your current membership and role determine access; a token's scopes can only narrow that access.

Roles, for people

Removing a membership removes that person's access to the organization. The last owner cannot be removed or demoted. See organizations and members.