Ir al contenido
ComStack

Autenticación de la API

Qué es esto

La API de ComStack acepta tres tipos de credenciales. Cuál utilizar depende de quién realiza la llamada y desde dónde.

ClienteCredencialNotas
Asistentes IA vía MCP (Claude, Cursor)OAuth 2.1 BearerEnrutamiento de proyecto por herramienta.
Servicios headless y CI vía MCPCabeceras x-api-key + x-project-idLimitado a un proyecto.
Portal web, extensión Chrome, voz en vivoFirebase ID Token (Authorization: Bearer)Usado por SPAs del dashboard y voz en vivo.

Cómo funciona

OAuth 2.1 (para clientes de agentes de IA)

OAuth 2.1 con PKCE (RFC 7636) y Registro Dinámico de Clientes (RFC 7591):

  1. Descubrimiento — GET /.well-known/oauth-authorization-server devuelve las URLs de los endpoints y el método PKCE soportado (S256).
  2. Registro — POST /oauth/register registra el cliente y devuelve un client_id. Sin secreto de cliente.
  3. Autorización — GET /oauth/authorize muestra la página de inicio de sesión de Firebase Auth.
  4. Emisión de código — POST /oauth/authorize/complete emite un código de autorización tras el inicio de sesión.
  5. Intercambio de token — POST /oauth/token devuelve un token de acceso (TTL de 1 hora) y un token de actualización (TTL de 30 días).
  6. Uso — cada POST /mcp incluye Authorization: Bearer <access_token>.

Los tokens de actualización se rotan automáticamente en cada uso. Presentar un token de actualización previamente rotado revoca toda la familia de tokens (protección contra ataques de repetición).

Claves API (para clientes máquina)

Ambas cabeceras son obligatorias en cada solicitud POST /mcp:

x-api-key:    <raw_key>
x-project-id: <project_id>

Las claves están limitadas a un solo proyecto. Un argumento project_id que no coincida con el alcance de la clave devuelve InvalidRequest. Las claves de servicio son la ruta recomendada a largo plazo para clientes headless.

Token de ID de Firebase (dashboard, extensión de Chrome)

Todas las rutas /api/* utilizan JWTs de Firebase Auth en Authorization: Bearer <token>. El token caduca después de 1 hora. Actualízalo usando user.getIdToken(true).

El middleware basado en roles verifica la pertenencia al proyecto en cada solicitud. Se aplica el rol mínimo requerido por el endpoint: manager para operaciones destructivas, cualquier miembro para lecturas.

Cuándo usar cada uno

  • OAuth: Integración orientada a humanos donde el usuario inicia sesión; la ruta estándar para Claude y Cursor.
  • Clave API: Pipelines de CI, tareas programadas, integraciones servidor a servidor.
  • Token de Firebase: Interfaz web personalizada construida sobre Firebase Auth.

Parámetros / campos / entradas

Resumen del endpoint OAuth:

EndpointMétodoPropósito
/.well-known/oauth-authorization-serverGETDescubrimiento de metadatos
/.well-known/oauth-protected-resourceGETMetadatos de recursos protegidos
/oauth/registerPOSTRegistro de cliente — devuelve client_id
/oauth/authorizeGETPágina de inicio de sesión de Firebase
/oauth/authorize/completePOSTEmite código de autorización
/oauth/tokenPOSTIntercambio de código o token de actualización

Ejemplo

Usando una clave API para llamar a la herramienta MCP get-project-state:

Terminal window
curl -X POST https://api.comstack.ai/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -H "x-project-id: your-project-id" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get-project-state",
      "arguments": { "project_id": "your-project-id" }
    }
  }'

Errores comunes

401 invalid_token — token de acceso caducado o desconocido. Usa el token de actualización mediante POST /oauth/token para obtener uno nuevo.

401 invalid_api_key — clave API no encontrada o revocada. Regénérala desde la configuración del proyecto.

403 Forbidden — autenticado pero con rol insuficiente para la operación solicitada.

403 (scope mismatch) — la cabecera x-project-id no coincide con el argumento project_id en la llamada a la herramienta.

429 Too Many Requests — los endpoints OAuth están limitados a 30 req/min/IP; los fallos de autenticación están limitados a 10/min/IP.

Relacionado

  • Servidor MCP — cómo los agentes de IA se conectan y enrutan las llamadas a herramientas
  • OAuth MCP — modelo de almacenamiento OAuth, TTLs de tokens, rotación de actualización
  • Seguridad MCP — modelo de amenazas y controles de seguridad
  • Permisos — roles y qué puede hacer cada uno

Última actualización: