API Tokens — Cmssy Docs

Überblick

API-Tokens sind cs_-Credentials, die den programmatischen Zugriff auf einen Workspace authentifizieren. Du erstellst sie im Cmssy-Admin und nutzt sie überall dort, wo Content außerhalb des Browser-Admin-UI gelesen oder geschrieben werden muss:

Der MCP-Server — Claude und andere KI-Clients verbinden sich mit einem Token, um deinen Content zu lesen und zu schreiben (Seiten, Blöcke, Modelle, Records, Formulare).
Das Content-Delivery-/GraphQL-API und der @cmssy/react-Daten-Client (createCmssyClient) — hole Content, Modelle, Records und Formulare in deine eigene Next.js-App.
Jeder Server-to-Server-API-Call, den du gegen das öffentliche GraphQL-API schreibst.

Jedes Token ist an ein bestimmtes Benutzerkonto gebunden. Was ein Token tun kann, bestimmen die Workspace-Rolle dieses Nutzers und sein isSuperAdmin-Flag — das Token selbst trägt keine Berechtigungen.

Token-Format: cs_ gefolgt von ~32 base64url-Zeichen (z. B. cs_abc1234...). Tokens werden gehasht gespeichert (bcrypt). Nur der cs_-Prefix plus die ersten 7 Zeichen bleiben für die UI-Anzeige im Klartext.

Ein Token erstellen

Öffne Settings → API / Tokens im Admin.
Klicke auf Create token.
Fülle aus:
- Name — für deine eigene Referenz (z. B. local dev, ci pipeline, production mcp).
- Expires in (days) — optional. Leer lassen für kein Ablaufdatum.
Klicke auf Create. Das vollständige Token wird in einem Dialog mit Kopier-Button angezeigt.

Der vollständige Token-Wert wird nur einmal angezeigt. Wenn du ihn verlierst, widerrufe ihn und erstelle einen neuen.

Ein Token verwenden

Mit dem MCP-Server

Verbinde Claude (oder einen beliebigen MCP-Client) mit deinem Workspace, indem du das Token in die MCP-Config deines Editors (.mcp.json) einträgst:

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

Das komplette Setup findest du unter MCP Server.

Mit dem @cmssy/react SDK

Das öffentliche Content-Delivery-API wird über deinen Workspace-Slug adressiert, der @cmssy/react-Client braucht also kein Token für veröffentlichte Reads. Konfiguriere ihn mit deinem workspaceSlug (apiUrl zeigt standardmäßig auf die cmssy cloud):

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

const config = {
  workspaceSlug: process.env.CMSSY_WORKSPACE_SLUG!,
};
const client = createCmssyClient(config);

// Fetch a published page
const page = await fetchPage(config, "/about");
// Run any GraphQL query (records, forms, site config)
const data = await client.query("{ /* GraphQL */ }");

Ein API-Token wird nur für authentifizierte Reads (Draft-Content) oder Writes gebraucht — übergib es als Bearer-Header über die Query-Optionen, z. B. client.query(doc, vars, { headers: { Authorization: "Bearer cs_..." } }).

Mit rohem GraphQL

Übergib das Token als Bearer-Header. Füge x-workspace-id hinzu, um den Request auf einen bestimmten Workspace zu scopen:

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

	Session-Cookie	API-Token
Erstellt durch	Login-Formular	Settings → API / Tokens
Genutzt von	Browser-Admin-UI	MCP / Delivery-API / SDK
Läuft ab	Beim Logout	Optionales Ablaufdatum pro Token
Widerruf	Logout oder Passwortänderung	Manuell, sofort
Workspace-Scope	Header pro Request	Header pro Request

Lese- vs. Schreibzugriff

Ein API-Token authentifiziert — es beweist, dass du Nutzer X bist. Was Nutzer X tun kann, bestimmen:

Workspace-Rolle — deine Rolle im Ziel-Workspace (Details unter Mitglieder & Rollen). Eine Nur-Lese-Rolle kann Content über das Delivery-API und SDK abrufen, aber nicht verändern; eine Editor- oder Admin-Rolle kann Content über den MCP-Server oder GraphQL-Mutationen lesen und schreiben.
isSuperAdmin-Flag — Plattform-Admins (Cmssy-Staff) haben erweiterte Berechtigungen für Operationen auf Plattformebene.

Tokens tragen KEINE eigenen Berechtigungen. Das bedeutet:

Der Entzug deiner Rolle in einem Workspace widerruft sofort alles, was deine Tokens in diesem Workspace tun können.
Das Hinzufügen einer Berechtigung zu einer Rolle propagiert zu allen Tokens von Nutzern mit dieser Rolle.
Du kannst kein Token mit weniger Berechtigungen ausstellen, als dein eigenes Konto hat — das Ziel ist Delegation, nicht Privilegien-Manipulation.

Tokens sind immer tenant-scoped: Jeder Request muss einen x-workspace-id- (oder --workspace-id-)Header tragen, und der Zugriff wird gegen deine Mitgliedschaft in genau diesem Workspace geprüft.

Widerrufen und rotieren

Der Widerruf ist sofort wirksam — kein Cache. Das Löschen eines Tokens unter Settings → API / Tokens entfernt es aus der Datenbank, und der nächste Request damit liefert 401.

Wenn ein Token leakt:

Widerrufe es sofort unter Settings → API / Tokens.
Erstelle einen Ersatz.
Aktualisiere deine MCP-Config, das SDK-.env oder das CI-Secret mit dem neuen Wert.

Best Practices

Ein Token pro Integration. Trenne dev / prod / jede CI-Pipeline. Der Widerruf eines geleakten Tokens sollte nicht drei andere Integrationen brechen.
Ablaufdaten für kurzlebige Tokens (CI-Pipelines, Demo-Umgebungen, Preview-Deployments).
Rotiere Produktions-Tokens regelmäßig — 90 Tage sind ein gängiger Rhythmus.
Committe Tokens nie in git. Nutze lokal .env (gitignored) und in CI den Secret-Manager deiner Plattform.

Troubleshooting

„Not authenticated“ (401)

Das Token wurde widerrufen, ist abgelaufen oder hat nie existiert. Prüfe den Status unter Settings → API / Tokens und bestätige, dass der cs_-Prefix zu dem passt, was in deinem Client hinterlegt ist.

„Permission denied“ / „Forbidden“ (403)

Das Token ist gültig, aber die Rolle des authentifizierten Nutzers erlaubt die Aktion nicht — zum Beispiel eine Nur-Lese-Rolle, die einen Write versucht. Prüfe die Workspace-Mitgliedsrolle unter Settings → Members. Wie Rollen auf Berechtigungen abbilden, steht unter Mitglieder-Authentifizierung.

„Workspace not found“

Der x-workspace-id-Header fehlt, ist falsch, oder der Nutzer ist kein Mitglied dieses Workspace. Verifiziere die ID unter Settings → Workspace.

Token funktioniert in einem Tool, aber nicht im anderen

Verschiedene Tools können unterschiedliche x-workspace-id-Werte senden. Bestätige, dass jedes Tool den Workspace nutzt, den du erwartest.