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

Abre Settings → API / Tokens en el admin.
Haz clic en Create token.
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.
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.

Crear un token sin navegador

Un agente pasa de no tener cuenta a tener un token que funciona con cuatro llamadas a la API GraphQL de administración, en https://api.cmssy.io/graphql. La primera llamada devuelve un accessToken; envíalo como Authorization: Bearer <accessToken> en las otras tres.

# 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 } }
}

Pasa el valor cs_ y el id del workspace al servidor MCP, o envíalos tú mismo en los headers Authorization y x-workspace-id. Un token creado con un workspaceId abre solo ese workspace y no llega a los ajustes de la cuenta.

Dos pasos que necesitan a una persona

Verificar la dirección de email. El registro envía un enlace de verificación. Todo lo anterior funciona antes de verificar la dirección, pero una cuenta que sigue sin verificar siete días después de crearse se elimina, junto con todas las organizaciones de las que es propietaria y todos sus workspaces. query { viewer { me { verificationDeadline } } } devuelve esa fecha, y null una vez verificada la dirección. Un null en una cuenta sin verificar significa que todavía no ha salido ningún email de verificación: pide otro con mutation { viewer { resendVerificationEmail { success message } } }, autenticado con el accessToken del registro. Regístrate con una dirección que lea una persona.
Cambiar de plan. Una organización nueva empieza en el plan Free, donde el carrito y el checkout responden PLAN_LIMIT_EXCEEDED. Cambiar a un plan de pago requiere una tarjeta en el checkout - ver Planes, límites y uso.

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 } from "@cmssy/react";
import { cmssy } from "@/cmssy.config";

const client = createCmssyClient(cmssy);

// Read published content with a GraphQL query (pages, records, forms, site config)
const data = await client.queryScoped(PUBLIC_PAGE_QUERY, { path: "/about" });

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":"{ viewer { me { email } } }"}'

Token vs sesión

	Cookie de sesión	Token de API
Creado por	Formulario de login	Settings → API / Tokens
Usado por	UI admin del navegador	MCP / API de entrega / SDK
Expira	Al cerrar sesión	Expiración opcional por token
Revocación	Cierre de sesión o cambio de contraseña	Manual, instantánea
Ámbito de workspace	Header por petición	Header por petició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:

Revócalo de inmediato en Settings → API / Tokens.
Crea uno de reemplazo.
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.