Aperçu

Les tokens API sont des identifiants cs_ qui authentifient l'accès programmatique à un workspace. Vous les créez dans l'admin Cmssy et les utilisez partout où du contenu doit être lu ou écrit en dehors de l'interface admin du navigateur :

Le serveur MCP — Claude et d'autres clients IA se connectent avec un token pour lire et écrire votre contenu (pages, blocs, modèles, enregistrements, formulaires).
L'API de diffusion de contenu / GraphQL et le client de données @cmssy/react (createCmssyClient) — récupérez contenu, modèles, enregistrements et formulaires dans votre propre application Next.js.
Tout appel API server-to-server que vous écrivez contre l'API GraphQL publique.

Chaque token est lié à un compte utilisateur précis. Ce qu'un token peut faire est déterminé par le rôle workspace de cet utilisateur et son flag isSuperAdmin — le token lui-même ne porte aucune permission.

Format du token : cs_ suivi d'environ 32 caractères base64url (p. ex. cs_abc1234...). Les tokens sont stockés hachés (bcrypt). Seuls le préfixe cs_ et les 7 premiers caractères restent en clair pour l'affichage dans l'UI.

Créer un token

Ouvrez Settings → API / Tokens dans l'admin.
Cliquez sur Create token.
Renseignez :
- Name — pour votre propre référence (p. ex. local dev, ci pipeline, production mcp).
- Expires in (days) — optionnel. Laissez vide pour aucune expiration.
Cliquez sur Create. Le token complet s'affiche dans une boîte de dialogue avec un bouton de copie.

La valeur complète du token n'est affichée qu'une seule fois. Si vous la perdez, révoquez le token et générez-en un nouveau.

Utiliser un token

Avec le serveur MCP

Connectez Claude (ou tout client MCP) à votre workspace en ajoutant le token à la config MCP de votre éditeur (.mcp.json) :

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

Voir MCP Server pour l'installation complète.

Avec le SDK @cmssy/react

L'API publique de diffusion de contenu est indexée par votre slug de workspace : le client @cmssy/react n'a donc besoin d'aucun token pour les lectures publiées. Configurez-le avec votre workspaceSlug (apiUrl pointe par défaut vers le cloud cmssy) :

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 */ }");

Un token API n'est nécessaire que pour les lectures authentifiées (contenu en brouillon) ou les écritures — passez-le en header Bearer via les options de requête, p. ex. client.query(doc, vars, { headers: { Authorization: "Bearer cs_..." } }).

Avec du GraphQL brut

Passez le token en header Bearer. Ajoutez x-workspace-id pour limiter la requête à un workspace précis :

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

	Cookie de session	Token API
Créé par	Formulaire de connexion	Settings → API / Tokens
Utilisé par	UI admin du navigateur	MCP / API de diffusion / SDK
Expire	À la déconnexion	Expiration optionnelle par token
Révocation	Déconnexion ou changement de mot de passe	Manuelle, instantanée
Portée workspace	Header par requête	Header par requête

Accès lecture vs écriture

Un token API authentifie — il prouve que vous êtes l'utilisateur X. Ce que l'utilisateur X peut faire est déterminé par :

Le rôle workspace — votre rôle dans le workspace cible (voir Membres & rôles pour les détails). Un rôle en lecture seule peut récupérer du contenu via l'API de diffusion et le SDK mais pas le modifier ; un rôle éditeur ou admin peut lire et écrire du contenu via le serveur MCP ou les mutations GraphQL.
Le flag isSuperAdmin — les admins de la plateforme (l'équipe Cmssy) ont des permissions élevées pour les opérations au niveau de la plateforme.

Les tokens ne portent PAS leurs propres permissions. Cela signifie :

Révoquer votre rôle dans un workspace révoque instantanément tout ce que vos tokens peuvent y faire.
Ajouter une permission à un rôle se propage à tous les tokens des utilisateurs ayant ce rôle.
Vous ne pouvez pas émettre un token avec moins de permissions que votre propre compte — l'objectif est la délégation, pas la manipulation de privilèges.

Les tokens sont toujours limités au tenant : chaque requête doit porter un header x-workspace-id (ou --workspace-id), et l'accès est vérifié contre votre appartenance à ce workspace précis.

Révocation et rotation

La révocation est instantanée — pas de cache. Supprimer un token depuis Settings → API / Tokens le retire de la base de données, et la requête suivante qui l'utilise renvoie 401.

Si un token fuite :

Révoquez-le immédiatement dans Settings → API / Tokens.
Créez un remplaçant.
Mettez à jour votre config MCP, le .env du SDK ou le secret CI avec la nouvelle valeur.

Bonnes pratiques

Un token par intégration. Séparez dev / prod / chaque pipeline CI. Révoquer un token qui a fuité ne devrait pas casser trois autres intégrations.
Dates d'expiration pour les tokens éphémères (pipelines CI, environnements de démo, déploiements de preview).
Faites tourner les tokens de production périodiquement — 90 jours est une cadence courante.
Ne commitez jamais de tokens dans git. Utilisez .env (gitignoré) en local et le gestionnaire de secrets de votre plateforme en CI.

Dépannage

« Not authenticated » (401)

Le token a été révoqué, a expiré ou n'a jamais existé. Vérifiez son statut dans Settings → API / Tokens et confirmez que le préfixe cs_ correspond à ce qui est stocké dans votre client.

« Permission denied » / « Forbidden » (403)

Le token est valide, mais le rôle de l'utilisateur authentifié n'autorise pas l'action — par exemple un rôle en lecture seule tentant une écriture. Vérifiez le rôle du membre du workspace dans Settings → Members. Voir Authentification des membres pour la correspondance entre rôles et permissions.

« Workspace not found »

Le header x-workspace-id est manquant, incorrect, ou l'utilisateur n'est pas membre de ce workspace. Vérifiez l'ID dans Settings → Workspace.

Le token fonctionne dans un outil mais pas dans un autre

Des outils différents peuvent envoyer des valeurs x-workspace-id différentes. Confirmez que chaque outil utilise bien le workspace attendu.