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.

Tworzenie tokena bez przeglądarki

Agent przejdzie od braku konta do działającego tokena czterema wywołaniami admin GraphQL API pod https://api.cmssy.io/graphql. Pierwsze wywołanie zwraca accessToken; wysyłaj go jako Authorization: Bearer <accessToken> w pozostałych trzech.

# 1. Create the account. The password needs 8-128 characters with an
#    uppercase letter, a lowercase letter and a digit.
mutation {
  auth { signup(input: { email: "you@example.com", password: "..." }) { accessToken } }
}

# 2. Create an organization. It owns the plan, the limits and billing.
mutation {
  organization { create(input: { name: "Acme" }) { id slug plan } }
}

# 3. Create a workspace in that organization.
mutation {
  workspace { create(input: { name: "Store", organizationId: "<organization id>" }) { id slug } }
}

# 4. Create the API token for that workspace. The secret is returned once.
mutation {
  apiToken { create(input: { name: "agent", workspaceId: "<workspace id>" }) { token } }
}

Przekaż wartość cs_ i id workspace do serwera MCP albo wysyłaj je sam w headerach Authorization i x-workspace-id. Token utworzony z workspaceId otwiera tylko ten workspace i nie sięga ustawień konta.

Dwa kroki, które wymagają człowieka

• Weryfikacja adresu email. Rejestracja wysyła link weryfikacyjny. Wszystko powyżej działa przed weryfikacją adresu, ale konto, które siedem dni po utworzeniu wciąż jest niezweryfikowane, zostaje usunięte razem ze wszystkimi organizacjami, których jest właścicielem, i wszystkimi ich workspace'ami. query { viewer { me { verificationDeadline } } } zwraca tę datę, a null po weryfikacji adresu. null na niezweryfikowanym koncie oznacza, że żaden email weryfikacyjny jeszcze nie wyszedł: poproś o kolejny przez mutation { viewer { resendVerificationEmail { success message } } }, uwierzytelniony accessToken z rejestracji. Rejestruj się adresem, który czyta człowiek.
• Zmiana planu. Nowa organizacja startuje na planie Free, na którym koszyk i checkout odpowiadają PLAN_LIMIT_EXCEEDED. Zmiana planu wymaga karty płatniczej przy checkoucie - zobacz Plany, limity i zużycie.

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

Publiczne content delivery API jest kluczowane Twoim slugiem workspace, więc klient @cmssy/react nie potrzebuje tokena do odczytu opublikowanej treści. Skonfiguruj go przez sam workspaceSlug (apiUrl domyślnie cmssy cloud):

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

const client = createCmssyClient(cmssy);

// Odczytaj opublikowaną treść zapytaniem GraphQL (strony, rekordy, formularze, site config)
const data = await client.queryScoped(PUBLIC_PAGE_QUERY, { path: "/about" });

Token API jest potrzebny tylko do uwierzytelnionych odczytów (treść draft) lub zapisów — przekaż go jako header Bearer przez opcje zapytania, np. client.query(doc, vars, { headers: { Authorization: "Bearer cs_..." } }).

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":"{ viewer { 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.