Tokens de API

Resumen

Los tokens de API son credenciales cs_ que autentican el acceso programático a un workspace. Los creas en el admin de Cmssy y los usas dondequiera que haya que leer o escribir contenido fuera de la interfaz admin del navegador:

• El servidor MCP — Claude y otros clientes de IA se conectan con un token para leer y escribir tu contenido (páginas, bloques, modelos, registros, formularios).
• La API de entrega de contenido / GraphQL y el cliente de datos @cmssy/react (createCmssyClient) — trae contenido, modelos, registros y formularios a tu propia app Next.js.
• Cualquier llamada API server-to-server que escribas contra la API GraphQL pública.

Cada token está ligado a una cuenta de usuario concreta. Lo que un token puede hacer lo determinan el rol de workspace de ese usuario y su flag isSuperAdmin — el token en sí no lleva permisos.

Formato del token: cs_ seguido de ~32 caracteres base64url (p. ej. cs_abc1234...). Los tokens se almacenan hasheados (bcrypt). Solo el prefijo cs_ más los primeros 7 caracteres se guardan en claro para mostrarlos en la UI.

Crear un token

1. Abre Settings → API / Tokens en el admin.
2. Haz clic en Create token.
3. Rellena:
   • Name — para tu propia referencia (p. ej. local dev, ci pipeline, production mcp).
   • Expires in (days) — opcional. Déjalo vacío para que no expire.
4. Haz clic en Create. El token completo se muestra en un diálogo con un botón de copiar.

El valor completo del token se muestra solo una vez. Si lo pierdes, revócalo y genera uno nuevo.

Usar un token

Con el servidor MCP

Conecta Claude (o cualquier cliente MCP) a tu workspace añadiendo el token a la config MCP de tu editor (.mcp.json):

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

Consulta MCP Server para la configuración completa.

Con el SDK @cmssy/react

La API pública de entrega de contenido se indexa por tu slug de workspace, así que el cliente @cmssy/react no necesita token para lecturas publicadas. Configúralo con tu workspaceSlug (apiUrl apunta por defecto al cloud de 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 de API solo se necesita para lecturas autenticadas (contenido en borrador) o escrituras — pásalo como header Bearer en las opciones de la consulta, p. ej. client.query(doc, vars, { headers: { Authorization: "Bearer cs_..." } }).

Con GraphQL crudo

Pasa el token como header Bearer. Añade x-workspace-id para acotar la petición a un workspace concreto:

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 sesión

Acceso de lectura vs escritura

Un token de API autentica — demuestra que eres el usuario X. Lo que el usuario X puede hacer lo determinan:

• El rol de workspace — tu rol en el workspace de destino (ver Miembros y roles para los detalles). Un rol de solo lectura puede obtener contenido a través de la API de entrega y el SDK pero no mutarlo; un rol de editor o admin puede leer y escribir contenido vía el servidor MCP o mutaciones GraphQL.
• El flag isSuperAdmin — los admins de plataforma (el equipo de Cmssy) tienen permisos elevados para operaciones a nivel de plataforma.

Los tokens NO llevan permisos propios. Esto significa que:

• Revocar tu rol en un workspace revoca al instante todo lo que tus tokens pueden hacer en ese workspace.
• Añadir un permiso a un rol se propaga a todos los tokens de los usuarios con ese rol.
• No puedes emitir un token con menos permisos que los de tu propia cuenta — el objetivo es la delegación, no la manipulación de privilegios.

Los tokens siempre están acotados al tenant: cada petición debe llevar un header x-workspace-id (o --workspace-id), y el acceso se comprueba contra tu membresía en ese workspace concreto.

Revocar y rotar

La revocación es instantánea — sin caché. Eliminar un token desde Settings → API / Tokens lo borra de la base de datos, y la siguiente petición que lo use devuelve 401.

Si un token se filtra:

1. Revócalo de inmediato en Settings → API / Tokens.
2. Crea uno de reemplazo.
3. Actualiza tu config MCP, el .env del SDK o el secreto de CI con el nuevo valor.

Buenas prácticas

• Un token por integración. Separa dev / prod / cada pipeline de CI. Revocar un token filtrado no debería romper otras tres integraciones.
• Fechas de expiración para tokens de corta vida (pipelines de CI, entornos de demo, despliegues de preview).
• Rota los tokens de producción periódicamente — 90 días es una cadencia habitual.
• Nunca commitees tokens a git. Usa .env (en gitignore) en local y el gestor de secretos de tu plataforma en CI.

Solución de problemas

«Not authenticated» (401)

El token fue revocado, expiró o nunca existió. Comprueba su estado en Settings → API / Tokens y confirma que el prefijo cs_ coincide con lo almacenado en tu cliente.

«Permission denied» / «Forbidden» (403)

El token es válido, pero el rol del usuario autenticado no permite la acción — por ejemplo, un rol de solo lectura intentando una escritura. Comprueba el rol del miembro del workspace en Settings → Members. Ver Autenticación de miembros para saber cómo los roles se corresponden con los permisos.

«Workspace not found»

El header x-workspace-id falta, es incorrecto, o el usuario no es miembro de ese workspace. Verifica el ID en Settings → Workspace.

El token funciona en una herramienta pero no en otra

Herramientas distintas pueden enviar valores x-workspace-id distintos. Confirma que cada herramienta usa el workspace que esperas.