Autenticación

C21 Live Control autentica dos clases de caller:

• Operadores humanos que entran a la UI web usan una cookie de sesión. La sesión se establece con el formulario de sign-in estándar contra el catálogo de usuarios.
• Callers no interactivos — la REST API y el servidor MCP — usan un API token, una credencial bearer emitida a un usuario existente.

Ambos caminos comparten el mismo modelo de autorización: cada llamada se asocia a un usuario, y el rol del usuario (System Administrator u Operator) controla lo que la llamada puede hacer.

API tokens

Crear

POST /c21apiv2/security/tokens emite un nuevo token. El cuerpo acepta:

La respuesta lleva el token completo exactamente una vez:

{
  "data": {
    "id": 12,
    "kid": "<key-id>",
    "token": "<la cadena bearer completa>",
    "name": "mcp-server-dev",
    "created_at": "2026-05-18T10:00:00Z",
    "expires_at": "2026-08-16T10:00:00Z"
  }
}

El servidor solo almacena el hash del token. Guarda el valor token devuelto en un secret manager — no se vuelve a devolver.

Crear un token requiere rol System Administrator.

Usar

Los callers pasan el token en la cabecera bearer estándar:

Authorization: Bearer <YOUR_API_TOKEN>

El token autentica como el usuario al que se emitió y hereda el rol de ese usuario.

Listar

GET /c21apiv2/security/tokens devuelve el catálogo de tokens. Cada fila expone id, kid, name, created_at, expires_at — el valor secreto no se devuelve nunca.

Revocar

DELETE /c21apiv2/security/tokens/{kid} revoca un token por su kid. Las llamadas siguientes con ese token devuelven 401 Unauthorized.

Rotar

No hay operación rotate. Para rotar un token sin downtime:

1. Crea un nuevo token (POST /c21apiv2/security/tokens).
2. Actualiza la integración para usar el nuevo token.
3. Confirma que la integración opera contra el nuevo token.
4. Revoca el antiguo (DELETE /c21apiv2/security/tokens/{kid}).

Límites de longitud de campo

Los campos username, first_name y last_name tienen un límite de 30 caracteres; email admite hasta 75. La API rechaza valores que excedan con un error de validación en HTTP 400 y nombra el campo ofensor en el envelope. El spec OpenAPI expone los maxLength en cada definición de campo.

Recomendaciones de almacenamiento

Trata los API tokens como secretos:

• Nunca commitees un token al control de versiones.
• Guarda los tokens en el secret store del host (Kubernetes secrets, HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, GitHub Actions secrets).
• Rota con calendario. Recrea el token, cambia, verifica, revoca el antiguo.
• Un token por caller. La auditoría se vuelve ambigua y la revocación se vuelve destructiva cuando los tokens se comparten entre servicios no relacionados.

FAQ