Autenticación

Connect tiene dos superficies de entrada, REST (/api/v1/*) y MCP (/mcp), y las dos autentican antes de resolver cualquier otra cosa: el método, el content-type y, sobre todo, la existencia de la tool. Quien llama sin credencial válida no puede distinguir «esa tool no existe» de «existe pero no tienes acceso». En un gateway multitenant, esa asimetría protege el catálogo de cada organización.

API keys

La credencial para llamar desde tu backend es una API key: prefijo connect_sk_, enviada como Authorization: Bearer. Se crean en connect.emisso.ai/api-keys, con nombre, permisos y vencimiento opcional.

El valor completo aparece una sola vez, al crearla. La base guarda su sha256 y un prefijo visible (connect_sk_7Qf3…) para nombrarla en la lista; si la pierdes no hay forma de recuperarla. Rotar es el mismo gesto: la opción «rotar» del dashboard crea un reemplazo con los mismos permisos y te ofrece revocar la anterior justo después de copiar el valor nuevo.

Con la clave en la mano, una llamada autenticada:

curl -X POST https://connect.emisso.ai/api/v1/tools/core.timestamp.now/execute \
  -H "Authorization: Bearer connect_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"input": {"timezone": "America/Santiago"}}'

Respuesta (200):

{
  "data": {
    "iso": "2026-08-07T14:32:11.412Z",
    "unix": 1786113131,
    "timezone": "America/Santiago"
  },
  "meta": {
    "request_id": "req_...",
    "tool_id": "core.timestamp.now",
    "plane": "action",
    "latency_ms": 12,
    "audit_status": "recorded"
  }
}

Toda respuesta trae este envelope {data, meta}, y el meta.request_id identifica la fila que la llamada dejó en la bitácora. Ahí la clave aparece como lo que es: una API key autentica como agente (actor_type: "agent"), y su id viaja aparte en la columna credential_id. La acción de un agente nunca se atribuye al humano que creó la clave.

Scopes

Cada clave lleva scopes, la lista de permisos que puede ejercer. Cada permiso representa una capacidad: varias tools pueden compartirlo, y un mismo conector puede declarar permisos separados. Una tool nueva reutiliza un permiso solo cuando conserva su alcance de autorización. Por ejemplo, sii:boletas:write es independiente de sii:write del Facturador: requiere una concesión explícita. Un permiso en la clave tampoco sustituye el permiso de la conexión ni la disponibilidad vigente de cada variante. El vocabulario completo:

Tres reglas gobiernan la lista:

• Todo es explícito. El formulario emite exactamente los permisos que marcaste; ni * ni comodines por conector (sii:*) se aceptan. Puedes otorgar hoy el scope de un sistema que aún no conectaste: queda inerte hasta que la conexión exista, y conectar el sistema después no obliga a re-acuñar la clave.
• Vacío significa cero autoridad, nunca «todos los permisos». Por eso una clave sin ningún permiso marcado no se puede crear; si construyes sobre este modelo, esa es la trampa a evitar.
• Lo que no termina en :read es sensible. El dashboard muestra una advertencia para cada permiso de escritura o solicitud autorizada. En la emisión de honorarios, el permiso de la API conserva la aprobación del profesional por documento o los límites de su permiso recurrente. La anulación exige su propio acceso y aprobación por documento; un permiso recurrente de emisión no la autoriza.

Una llamada que exige un scope que la clave no tiene responde 403 scope_not_granted, con su suggested_fix en el envelope (catálogo de errores).

OAuth 2.1 para clientes MCP

Un cliente MCP interactivo (Claude, ChatGPT, un agente de terceros) no maneja una API key estática, así que /mcp es además un OAuth 2.1 Resource Server y el enrolamiento ocurre solo. Al agregar https://connect.emisso.ai/mcp en el cliente:

1. El cliente descubre los metadatos del recurso protegido (/.well-known/oauth-protected-resource) y, desde ahí, el authorization server.
2. Se registra en caliente en /register (Dynamic Client Registration): sin coordinación previa y sin client secret, porque solo se admiten clientes públicos.
3. Abre /authorize con PKCE S256 obligatorio; una persona inicia sesión, elige la organización y aprueba.
4. Canjea el código en /token y recibe un access token connect_at_ y un refresh token connect_rt_.

El parámetro resource del flujo (RFC 8707) liga el token a la audiencia de este gateway, y cada llamada la verifica: el token no sirve contra ningún otro recurso. Y autentica como usuario: la bitácora registra actor_type: "user" con la identidad de quien aprobó, en vez de un agente anónimo.

Al remover a una persona de la organización, se revocan sus autorizaciones y se invalidan sus códigos de consentimiento pendientes. Un código emitido antes de la remoción no permite recuperar el acceso; si vuelves a invitarla, debe autorizar de nuevo al cliente.

El challenge

Una llamada a /mcp sin bearer no revela nada del catálogo; responde el challenge estándar:

curl -i -X POST https://connect.emisso.ai/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Respuesta (cabeceras recortadas):

HTTP/2 401
www-authenticate: Bearer resource_metadata="https://connect.emisso.ai/.well-known/oauth-protected-resource"

{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"unauthorized"}}

Ese header le dice al cliente dónde iniciar el flujo OAuth. El mismo challenge protege /api/v1/*. La falla queda registrada en security_events con el prefijo de la credencial; a la bitácora no llega, porque una falla de autenticación no tiene organización que la reciba.

Cuándo usar cuál

Las dos superficies aceptan las dos credenciales; la elección real es quién custodia el secreto.

Próximos pasos

• Tu primera llamada: el quickstart con un dato real, sin conexión de por medio.
• Conectar un sistema: del enlace de conexión a la primera sincronización.
• MCP: las tres meta-tools y el recorrido que hace un agente.