BCMS Logo

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:

  1. Go to Settings → API Keys.

  2. Click Add New Key.

  3. Set a name (required) and description (optional).

  4. 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

main.jpg

Editing a Key

To update a key:

  1. Click on the key name or the pencil icon.

  2. Update its name, description, or permissions.

  3. 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 key

  • secret: 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:

  1. Open the key’s settings.

  2. Check the Blocked option.

  3. 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:

  1. Click Delete on the key.

  2. 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.

PreviousSettings
NextPermissions