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.

Cliente	Credencial	Notas
Asistentes IA vía MCP (Claude, Cursor)	OAuth 2.1 Bearer	Enrutamiento de proyecto por herramienta.
Servicios headless y CI vía MCP	Cabeceras x-api-key + x-project-id	Limitado a un proyecto.
Portal web, extensión Chrome, voz en vivo	Token ID de Firebase (Authorization: Bearer)	Usado por SPAs del dashboard y voz en vivo.

Cómo funciona

OAuth 2.1 (para clientes de agentes 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 refresco (TTL de 30 días).
6. Uso — cada POST /mcp incluye Authorization: Bearer <access_token>.

Los tokens de refresco se rotan automáticamente en cada uso. Presentar un token de refresco 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 ID de Firebase (dashboard, extensión Chrome)

Todas las rutas /api/* utilizan JWTs de Firebase Auth en Authorization: Bearer <token>. El token expira después de 1 hora. Refresca 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 Firebase: Interfaz web personalizada construida sobre Firebase Auth.

Parámetros / campos / entradas

Resumen de endpoints OAuth:

Endpoint	Método	Propósito
/.well-known/oauth-authorization-server	GET	Descubrimiento de metadatos
/.well-known/oauth-protected-resource	GET	Metadatos de recursos protegidos
/oauth/register	POST	Registro de cliente — devuelve client_id
/oauth/authorize	GET	Página de inicio de sesión de Firebase
/oauth/authorize/complete	POST	Emite código de autorización
/oauth/token	POST	Intercambio de código o token de refresco

Ejemplo

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

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 expirado o desconocido. Usa el token de refresco vía 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 peticiones/min/IP; los fallos de autenticación están limitados a 10/min/IP.

Relacionado

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