API keys

An API key is a long-lived credential for connecting something to Kreel that isn’t a person clicking through a login screen: the kreel CLI, a script, an automation tool like n8n, or an MCP client that doesn’t support OAuth yet. If you’re connecting Claude or ChatGPT as a remote MCP connector, you don’t need a key at all - see Connect an AI agent for the OAuth path. Use a key when you need one.

Create a key

1. Sign in to Kreel at app.kreel.ai.
2. In the left navigation, click API keys.
3. Click + Create key.
4. Fill in the form:
   • Label - a name to remember it by, for example “Claude Desktop - Paul”.
   • Surface - what will use the key: Claude Desktop, Claude Code, ChatGPT, Kreel CLI, or Other.
   • Scopes - Read and Write are on by default; PII access is off by default (see Scopes below).
5. Click Create →.

Key format

A Kreel API key looks like this:

kreel_live_8f3e12a9c47b0d5e2f6a1c8b3d9e0f4a7b2c5d8e1f0a3b6c9d2e5f8a1b4c7d0e

The full key is shown to you once, right after you click Create. Copy it immediately and store it somewhere safe. After that, Kreel only shows a shortened form (the prefix plus the last few characters) and stores a hash of the full key, not the key itself. If you lose the key, you cannot recover it - you have to rotate it for a new one.

Verify the prefix

New Kreel keys start with kreel_live_. Keys issued before the rename start with bpai_live_ and keep working - you don’t need to rotate them, and Kreel will accept them for as long as they exist. If something asks you for a key and shows a prefix that is neither of those as an example, that’s a placeholder, not a real format.

Scopes

Each key carries one or more scopes that control what it can do:

• Read - view brand performance data. On by default.
• Write - update Brand Knowledge Base content (profile, sections, competitors, learnings) and create drafts or uploads. On by default.
• PII access - required for data that includes customer-level personal information. Off by default.

A key can never carry more access than your own role in the workspace currently allows. If you ask for a scope your role doesn’t permit, key creation is rejected; if you don’t specify scopes at all, Kreel quietly limits the key to what your role allows.

Which brands a key can reach

A key is scoped to one workspace, and owned by the person who created it. It reaches every brand in that workspace that its owner can currently access, checked live on every call, not a fixed list saved at creation time.

This matters in practice:

• If your role or brand access changes later (for example, you’re removed from a brand), any key you created loses that access immediately, without anyone touching the key.
• A key never reaches your other workspaces, even if you have access to brands there.
• To see exactly which brands a key can reach right now, open the key on the API keys page and use its Brands toggle.

Older keys

Some older keys are bound to a single brand instead of a workspace. These behave the same way for that one brand, but never expand to reach anything else, even if the owner gains access to more brands later.

Choosing a brand per call

A key can reach multiple brands, so each call still has to say which brand it means:

• REST calls pass ?client_id=<brand id> on the request.
• MCP tools take a brand argument.
• The CLI uses the --brand flag, or the KREEL_BRAND environment variable as a default.

If a key only reaches one brand, you can usually omit this and Kreel uses that single brand automatically. See Connect an AI agent and The Kreel CLI for the full setup on each surface.

Rotate a key

Rotating replaces a key’s secret value while keeping its scopes and brand access. Use it when a key needs a fresh secret but you don’t want to reconfigure everything that uses it.

On the API keys page, find the key and click Rotate. Kreel creates a new key (named after the old one, with ” (rotated)” appended) and immediately deactivates the old one. The new key’s full value is shown once, the same as at creation - copy it and update wherever the old key was in use.

Rotating breaks the old key immediately

The old key stops working as soon as the new one is issued. Update every place that uses it (agent config, .env file, kreel auth login) before or right after you rotate, or that connection will start failing.

Only an active key can be rotated. A revoked key can’t be rotated back to life - create a new key instead.

Revoke a key

On the API keys page, find the key, click Revoke, and confirm. The key stops working immediately. This cannot be undone; if you need access again, create a new key.

Revoke a key whenever it’s no longer needed, or right away if it may have leaked.

Who can manage a key

A key can be managed (rotated or revoked) by the person who created it, or by an owner or admin of its workspace.

Keep your key safe

Treat an API key like a password

Anyone holding a live key can read (and, with write scope, modify) everything it reaches - full brand data, not just a sample. Don’t paste keys into chat messages, commit them to source control, or store them in plain text. Use your password manager or your tool’s secrets store instead.

If a key leaks or you’re not sure, rotate it right away. The leaked key stops working the moment you do.

For background on how workspaces, brands, and seats relate to each other, see Workspaces, brands, and seats.

Need help?

Email support@kreel.ai and we will help you sort it out.