API Tokens

Overview

API tokens are cs_ credentials that authenticate programmatic access to a workspace. You create them in the cmssy admin and use them anywhere content needs to be read or written outside the browser admin UI:

• The MCP server — Claude and other AI clients connect with a token to read and write your content (pages, blocks, models, records, forms).
• The content delivery / GraphQL API and the @cmssy/react data client (createCmssyClient) — fetch content, models, records, and forms into your own Next.js app.
• Any server-to-server API call you write against the public GraphQL API.

Every token is tied to a specific user account. What a token can do is determined by that user's workspace role and their isSuperAdmin flag — the token itself carries no permissions.

Token format: cs_ followed by ~32 base64url characters (e.g. cs_abc1234...). Tokens are stored hashed (bcrypt). Only the cs_ prefix plus the first 7 characters are kept in plaintext for UI display.

Creating a token

1. Open Settings → API / Tokens in the admin.
2. Click Create token.
3. Fill in:
   • Name — for your own reference (e.g. local dev, ci pipeline, production mcp).
   • Expires in (days) — optional. Leave empty for no expiration.
4. Click Create. The full token is shown in a dialog with a copy button.

The full token value is shown only once. If you lose it, revoke it and generate a new one.

Using a token

With the MCP server

Connect Claude (or any MCP client) to your workspace by adding the token to your editor's MCP config (.mcp.json):

{
  "mcpServers": {
    "cmssy": {
      "command": "npx",
      "args": [
        "-y", "@cmssy/mcp-server@latest",
        "--token", "cs_your_token_here",
        "--workspace-id", "507f1f77bcf86cd799439011"
      ]
    }
  }
}

See MCP Server for complete setup.

With the @cmssy/react SDK

Use the token to create a delivery client and fetch content into your Next.js app:

import { createCmssyClient } from "@cmssy/react";

const client = createCmssyClient({
  token: process.env.CMSSY_TOKEN!,
  workspaceId: process.env.CMSSY_WORKSPACE_ID!,
});

const page = await client.getPage("/about");
const posts = await client.listRecords("blog");

With raw GraphQL

Pass the token as a Bearer header. Add x-workspace-id to scope the request to a specific workspace:

curl https://api.cmssy.io/graphql \
  -H "Authorization: Bearer cs_your_token_here" \
  -H "x-workspace-id: 507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ me { email } }"}'

Token vs session

Read vs write access

An API token authenticates — it proves you are user X. What user X can do is determined by:

• Workspace role — your role in the target workspace (see Members & Roles for details). A read-only role can fetch content through the delivery API and SDK but cannot mutate it; an editor or admin role can read and write content via the MCP server or GraphQL mutations.
• isSuperAdmin flag — platform admins (cmssy staff) have elevated permissions for platform-level operations.

Tokens do NOT carry their own permissions. This means:

• Revoking your role in a workspace instantly revokes everything your tokens can do in that workspace.
• Adding a permission to a role propagates to all tokens for users with that role.
• You cannot issue a token with less permission than your own account has — the goal is delegation, not privilege manipulation.

Tokens are always tenant-scoped: every request must carry an x-workspace-id (or --workspace-id) header, and access is checked against your membership in that specific workspace.

Revoking and rotating

Revocation is instant — no cache. Deleting a token from Settings → API / Tokens removes it from the database, and the next request using it returns 401.

If a token leaks:

1. Revoke it immediately in Settings → API / Tokens.
2. Create a replacement.
3. Update your MCP config, SDK .env, or CI secret with the new value.

Best practices

• One token per integration. Separate dev / prod / each CI pipeline. Revoking a leaked token shouldn't break three other integrations.
• Expiration dates for short-lived tokens (CI pipelines, demo environments, preview deployments).
• Rotate production tokens periodically — 90 days is a common cadence.
• Never commit tokens to git. Use .env (gitignored) locally and your platform's secret manager in CI.

Troubleshooting

“Not authenticated” (401)

The token was revoked, expired, or never existed. Check status in Settings → API / Tokens and confirm the cs_ prefix matches what's stored in your client.

“Permission denied” / “Forbidden” (403)

The token is valid, but the authenticated user's role doesn't allow the action — for example a read-only role attempting a write. Check the workspace member role in Settings → Members. See Member Authentication for how roles map to permissions.

“Workspace not found”

The x-workspace-id header is missing, incorrect, or the user isn't a member of that workspace. Verify the ID in Settings → Workspace.

Token works in one tool but not another

Different tools may send different x-workspace-id values. Confirm each tool is using the workspace you expect.