Tokeny API

Przegląd

Tokeny API to credentiale cs_ uwierzytelniające programatyczny dostęp do workspace. Tworzysz je w adminie cmssy i używasz wszędzie tam, gdzie treść trzeba odczytać lub zapisać poza UI admina w przeglądarce:

• Serwer MCP — Claude i inne klienty AI łączą się tokenem aby czytać i zapisywać Twoją treść (strony, bloki, modele, rekordy, formularze).
• Content delivery / GraphQL API oraz klient danych @cmssy/react (createCmssyClient) — pobieraj treść, modele, rekordy i formularze do własnej aplikacji Next.js.
• Dowolne wywołanie API server-to-server które piszesz do publicznego GraphQL API.

Każdy token jest powiązany z konkretnym kontem użytkownika. Co token może zrobić zależy od roli tego użytkownika w workspace i flagi isSuperAdmin — token sam nie niesie uprawnień.

Format tokena: cs_ + ~32 znaków base64url (np. cs_abc1234...). Tokeny są przechowywane jako hash (bcrypt). Tylko prefix cs_ + pierwsze 7 znaków zostaje w plaintext do wyświetlania w UI.

Tworzenie tokena

1. Otwórz Settings → API / Tokens w adminie.
2. Kliknij Create token.
3. Uzupełnij:
   • Name — dla Twojej referencji (np. local dev, ci pipeline, production mcp).
   • Expires in (days) — opcjonalne. Puste = bez wygasania.
4. Kliknij Create. Pełna wartość tokena pokaże się w dialogu z przyciskiem kopiowania.

Pełna wartość tokena pokazywana jest tylko raz. Jeśli stracisz, odwołaj i wygeneruj nowy.

Używanie tokena

Z serwerem MCP

Podłącz Claude (lub dowolny klient MCP) do workspace dodając token do MCP configu edytora (.mcp.json):

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

Pełny setup: MCP Server.

Z SDK @cmssy/react

Użyj tokena aby utworzyć klienta delivery i pobierać treść do aplikacji Next.js:

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");

Z surowym GraphQL

Przekaż token w headerze Bearer. Dodaj x-workspace-id aby zascope'ować request do konkretnego 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 sesja

Dostęp do odczytu vs zapisu

Token API uwierzytelnia — potwierdza że jesteś użytkownikiem X. Co użytkownik X może zrobić zależy od:

• Roli w workspace — Twojej roli w docelowym workspace (zobacz Członkowie i role po szczegóły). Rola tylko do odczytu pozwala pobierać treść przez delivery API i SDK, ale nie modyfikować jej; rola edytora lub admina pozwala czytać i zapisywać treść przez serwer MCP lub mutacje GraphQL.
• Flagi isSuperAdmin — platform adminowie (staff cmssy) mają podwyższone uprawnienia do operacji na poziomie platformy.

Tokeny NIE niosą własnych uprawnień. To oznacza że:

• Odwołanie Twojej roli w workspace natychmiast odwołuje wszystko co Twoje tokeny mogą zrobić w tym workspace.
• Dodanie uprawnienia do roli propaguje się do wszystkich tokenów użytkowników z tą rolą.
• Nie możesz wydać tokena z mniejszymi uprawnieniami niż Twoje konto — sens to delegacja, nie manipulacja uprawnieniami.

Tokeny są zawsze scope'owane do tenanta: każdy request musi nieść header x-workspace-id (lub --workspace-id), a dostęp jest sprawdzany względem Twojego członkostwa w tym konkretnym workspace.

Odwołanie i rotacja

Odwołanie jest natychmiastowe — bez cache. Usunięcie tokena z Settings → API / Tokens usuwa go z bazy, a następny request go używający zwraca 401.

Jeśli token wyciekł:

1. Odwołaj natychmiast w Settings → API / Tokens.
2. Utwórz zastępczy.
3. Zaktualizuj MCP config, SDK .env lub secret CI nową wartością.

Dobre praktyki

• Jeden token na integrację. Oddziel dev / prod / każdy pipeline CI. Odwołanie wyciekłego tokena nie powinno zepsuć trzech innych integracji.
• Daty wygaśnięcia dla krótkotrwałych tokenów (pipeline CI, środowiska demo, preview deployments).
• Rotuj tokeny produkcyjne okresowo — 90 dni to popularny cadence.
• Nigdy nie commituj tokenów do git. Użyj .env (gitignored) lokalnie i secret managera Twojej platformy w CI.

Troubleshooting

„Not authenticated” (401)

Token został odwołany, wygasł lub nigdy nie istniał. Sprawdź status w Settings → API / Tokens i potwierdź że prefix cs_ pasuje do wartości w Twoim kliencie.

„Permission denied” / „Forbidden” (403)

Token jest ważny, ale rola uwierzytelnionego użytkownika nie pozwala na daną akcję — np. rola tylko do odczytu próbująca zapisu. Sprawdź rolę członka workspace w Settings → Members. Zobacz Uwierzytelnianie członków jak role mapują się na uprawnienia.

„Workspace not found”

Header x-workspace-id brakuje, jest nieprawidłowy, albo użytkownik nie jest członkiem tego workspace. Zweryfikuj ID w Settings → Workspace.

Token działa w jednym narzędziu ale nie w innym

Różne narzędzia mogą wysyłać różne wartości x-workspace-id. Potwierdź że każde narzędzie używa workspace jaki oczekujesz.