Working with API keys
API Keys in BCMS connect your app to your content. Every API key defines what parts of your CMS can be accessed, and whether the access is read-only or can mutate content.
You can create multiple keys with different roles for different environments or use cases - for example, a public website, internal dashboard, or upload tool.
Creating and Managing API Keys
To create a new key:
Go to Settings → API Keys.
Click Add New Key.
Set a name (required) and description (optional).
Choose permissions for each of the templates you've created
You can configure whether the key:
Can read specific resources
Can write/update resources (mutate content)
Can access all templates or just a selection

Editing a Key
To update a key:
Click on the key name or the pencil icon.
Update its name, description, or permissions.
Changes take effect immediately.
⚠️ Be careful: If you remove a permission, any app using that key may lose access instantly.
API Key Structure
Each API key includes:
id
: Public part of the keysecret
: Private part (keep this safe)A combination of permissions, tightly scoped to reduce security risk.
You’ll pass both id
and secret
when creating a BCMS Client:
import { Client } from '@thebcms/client'; const bcms = new Client( process.env.BCMS_ORG_ID!, process.env.BCMS_INSTANCE_ID!, { id: process.env.BCMS_API_KEY_ID!, secret: process.env.BCMS_API_KEY_SECRET!, }, );
Use Case: Media Uploads
For frontend apps that need to upload media (e.g., uploading images via a form), we recommend using a media-specific API key:
const bcmsMediaClient = new Client( process.env.NEXT_PUBLIC_BCMS_ORG_ID!, process.env.NEXT_PUBLIC_BCMS_INSTANCE_ID!, { id: process.env.NEXT_PUBLIC_BCMS_MEDIA_API_KEY_ID!, secret: process.env.NEXT_PUBLIC_BCMS_MEDIA_API_KEY_SECRET!, }, { injectSvg: true, }, );
This keeps your main API key private and reduces the risk if the media key is ever exposed. See Working with Media for more details.
Blocking a Key
You can block a key without deleting it:
Open the key’s settings.
Check the Blocked option.
Save the changes.
A blocked key immediately loses access to all resources.
This is useful for:
Temporary access suspensions
Deactivating a key during a breach or test phase
Deleting a Key
To permanently remove a key:
Click Delete on the key.
Confirm the deletion.
Deleting a key immediately cuts off access for all apps using it. Make sure you're not using it in production before confirming.
Best Practices
Use separate keys for each environment (e.g., dev, staging, production).
Limit permissions to the minimum necessary.
For client-side code, create read-only keys scoped to specific templates.
Use a dedicated media key for client side, uploads etc.
Store keys in environment variables - never hardcode them in source code.