Autenticación
API keys con permisos explícitos para tu backend, OAuth 2.1 para clientes MCP: cómo se autentica cada llamada al gateway.
Emisso 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.
Para cambiar los permisos, el nombre o las conexiones de una clave activa no hace falta rotarla: abre la clave en connect.emisso.ai/api-keys y elige Editar clave. El valor y el vencimiento no cambian, y la llamada siguiente ya usa los permisos nuevos, así que no tocas nada en tu integración. Editar requiere un rol de owner o admin; para cambiar el vencimiento, rota la clave.
Con la clave en la mano, una llamada autenticada. Lista las conexiones a las que alcanza la clave, el permiso que trae toda clave nueva:
curl -X POST https://connect.emisso.ai/api/v1/tools/conexiones.estado.consultar/execute \
-H "Authorization: Bearer connect_sk_..." \
-H "Content-Type: application/json" \
-d '{"input": {}}'Respuesta (200), recortada:
{
"data": {
"conexiones": [
{ "id": "conn_9tKfR2mQx4Vb", "sistema": "sii", "nombre": "Comercial Aurora SpA", "estado": "active", "datosListos": true }
]
},
"meta": {
"request_id": "req_...",
"tool_id": "conexiones.estado.consultar",
"plane": "action",
"latency_ms": 24,
"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.
Indicar la conexión en las tools
Para todas las tools de un sistema conectado, Authorization identifica tu clave y
X-Connect-Connection: conn_... identifica
la conexión sobre la que llamas la tool. Ambos son necesarios, incluso con una sola conexión.
Las tools de plataforma o datos abiertos no necesitan ese header; por ejemplo, conexiones.*,
core.*, indicadores.* y echo.*. Toda ejecución de tool requiere Content-Type: application/json.
Obtén el id con GET /api/v1/connections; usa el sistema que corresponda al id de la tool.
Por ejemplo, sii.rcv.consultar necesita una conexión SII y santander_empresas.conexion.sincronizar
una conexión Santander. En el endpoint de control POST /api/v1/connections/{conn}/syncs, la conexión
va en la ruta. Consulta las rutas exactas.
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:
| Scope | Qué permite |
|---|---|
sii:read | Compras y ventas (RCV), boletas, guías de despacho, boletas de honorarios, las declaraciones F29 y los XML emitidos y recibidos disponibles en el respaldo del SII |
sii:boletas:write | Preparar y emitir boletas 39/41 mediante e-Boleta, con consentimiento y evidencia vigente por variante; ambas operaciones permanecen cerradas sin esa evidencia |
sii:carpeta_tributaria:generar | Crear solicitudes puntuales consentidas de carpeta tributaria y consultar su resultado |
sii:honorarios:write | Crear solicitudes de boletas de honorarios y propuestas de permiso recurrente, preparar borradores y consultar resultados bajo autorización profesional. Beta cerrada por organización; la emisión requiere habilitación privada y las aprobaciones aplicables |
sii:honorarios:annul | Crear y consultar solicitudes de anulación de boletas verificadas por Emisso, previsualizarlas y cancelarlas antes del envío. El envío fiscal requiere habilitación privada por organización, protocolo certificado y aprobación del profesional para cada documento; el permiso por sí solo no lo autoriza |
sii:write | Previsualizar, emitir y anular documentos en el Facturador Gratuito del SII, y descargar su PDF oficial |
bci_360:read | Saldos, movimientos y nóminas de pago de BCI 360 |
bci_pyme:read | Saldos y movimientos del Banco BCI |
banco_security:read | Saldos, movimientos, transferencias y nóminas del Banco Security |
bice_empresas:read | Saldos y movimientos del Banco BICE |
bch_empresas:read | Saldos, movimientos de cuentas, movimientos de tarjetas y cartolas del Banco de Chile |
banco_estado:read | Saldos y movimientos de BancoEstado |
santander_empresas:read | Saldos, movimientos y estado conservado de transferencias preparadas del Banco Santander |
santander_empresas:tef:preparar | Beta privada: preparar TEF a destinatarios inscritos; un apoderado autoriza en Office Banking. Exige permiso explícito en la clave y conexión |
scotiabank_empresas:read | Saldos y movimientos de Scotiabank Empresas |
itau_empresas:read | Saldos, movimientos y transferencias de Banco Itaú Empresas |
itau_corporate:read | Saldos, movimientos y nóminas de pago masivo de Itaú Corporate |
global66:read | Cuentas y saldos por moneda, compras con tarjeta y beneficiarios de Global66 Empresas. Movimientos, catálogos y validación de pagos requieren el acceso por API de Global66, todavía no disponible. Beta habilitada por organización; pendiente de piloto real |
global66:pagos | Ejecutar pagos y conversiones por la API de Global66, todavía no disponible en la beta. Mueve dinero: exige una preparación vigente del mismo actor, clave de idempotencia estable y permiso explícito en la clave y la conexión |
global66:raas | Ejecutar pagos RaaS por la API de Global66, todavía no disponible en la beta. Exige preparación vigente, permiso explícito y habilitación del proveedor para la empresa; no se concede con comodines ni perfiles |
global66:preparar | Cotizar y preparar operaciones del asistente de Global66 para aprobación humana en Global66. No mueve dinero; exige permiso explícito en la clave y la conexión |
previred:read | Planillas pagadas, cotizaciones por trabajador, deuda previsional, archivo para el F30-1, certificados de cotizaciones, empresas de la credencial, nóminas actuales y la descarga de sus documentos |
tgr:read | Convenios de pago con la Tesorería: resoluciones, estado de pago, convenios con cuotas y el detalle de cada convenio |
sunat_beta:read | SUNAT (beta, organizaciones de Perú): verificar el acceso, sincronizar períodos y propuestas de compras y ventas SIRE, y consultar los datos guardados. Requiere conexión validada; no presenta registros ni emite comprobantes |
bbva_peru_beta:read | BBVA Perú (beta, organizaciones de Perú): sincronizar cuentas, saldos, movimientos y cartolas, y consultar los datos guardados. Requiere conexión validada |
pjud:read | Cartera judicial autorizada, actuaciones, documentos, novedades y cobertura del piloto civil |
mercadopago:read | Pagos recibidos, reembolsos y comisiones ya sincronizados de una cuenta de Mercado Pago |
mercadopago:write | Solicitar reportes puntuales de hasta 60 días con consentimiento previo del dueño o administrador de la conexión. La API y MCP no otorgan ese consentimiento |
mercadopublico:read | Consultar el estado y descargar los adjuntos ya obtenidos de una licitación de Mercado Público |
mercadopublico:write | Pedir la descarga de los adjuntos de una licitación de Mercado Público |
meta_ads:read | Gasto diario estimado de una cuenta publicitaria de Meta, al total de la cuenta y por campaña, ya sincronizado (piloto privado). No son facturas ni cobros de Meta |
shopify:pedidos | Leer en vivo los datos de la tienda Shopify conectada, sus pedidos con montos, transacciones y reembolsos, y la suma de sus ventas de un período, sin datos de clientes (piloto privado). Se otorga solo nombrándolo |
shopify:productos | Leer en vivo los productos y variantes de la tienda Shopify conectada, con SKU y precios (piloto privado). Se otorga solo nombrándolo |
shopify:inventario | Leer en vivo el stock por ubicación de un ítem de inventario de la tienda Shopify conectada (piloto privado). Se otorga solo nombrándolo |
x:identity | Comprobar en vivo la identidad y los permisos de la cuenta de X conectada. Beta privada por organización; se otorga sólo nombrándolo |
x:readonly | Verificar por ID una publicación de la cuenta de X conectada, si el proveedor concedió lectura. No sincroniza historial ni métricas; beta privada |
x:publish | Publicar texto e imágenes admitidos por X en la cuenta conectada, con autorización y clave UUID estable para un único intento. Beta privada; no incluye video ni Reels |
linkedin:identity | Comprobar en vivo la identidad y los permisos de la cuenta de LinkedIn conectada. Beta privada por organización; se otorga sólo nombrándolo |
linkedin:readonly | Verificar por ID una publicación de la cuenta de LinkedIn conectada, si el proveedor concedió lectura. No sincroniza historial ni métricas; beta privada |
linkedin:publish | Publicar texto e imágenes admitidos por LinkedIn en la cuenta conectada, con autorización y clave UUID estable para un único intento. Beta privada; no incluye video ni Reels |
instagram:identity | Comprobar en vivo la identidad y los permisos de la cuenta de Instagram conectada. Beta privada por organización; se otorga sólo nombrándolo |
instagram:readonly | Verificar por ID una publicación de la cuenta de Instagram conectada, si el proveedor concedió lectura. No sincroniza historial ni métricas; beta privada |
instagram:publish | Publicar texto e imágenes admitidos por Instagram en la cuenta conectada, con autorización y clave UUID estable para un único intento. Beta privada; no incluye video ni Reels |
instagram:media | Cargar e inspeccionar archivos y adecuarlos a un formato de Instagram en Emisso, con original y archivo preparado privados durante 7 días. No publica ni usa la cuenta de Instagram; además, un propietario o administrador debe habilitarlo en los ajustes de la conexión. Beta privada |
indicadores:read | UF, dólar, euro, IPC y UTM |
core:read | Diagnóstico: hora del servidor |
echo:read | Diagnóstico: eco |
conexiones:read | Ver qué sistemas están conectados, si ya sincronizaron y qué herramientas ofrecen |
conexiones:write | Emitir enlaces de un solo uso donde una persona entrega sus credenciales reales del banco o del SII, y crear la conexión de un sistema que no pide clave (Mercado Público), que se cobra como cualquier otra |
conexiones:disable | Deshabilitar una conexión: deja de sincronizar y de sumarse al cobro, sin borrar nada |
conexiones:enable | Habilitar una conexión deshabilitada, que vuelve a sincronizar y a sumarse al cobro del plan |
conexiones:rename | Cambiar el nombre visible de una conexión en el panel, la bitácora y los cobros, sin tocar su credencial ni sus datos |
conexiones:delete | Eliminar una conexión junto con su credencial guardada, sus datos sincronizados, su historial de sincronizaciones y sus webhooks. Es irreversible |
conexiones:grupos:read | Ver los grupos con que la organización ordena sus conexiones en el panel, solo con las conexiones que alcanza la clave |
conexiones:grupos:write | Crear grupos y mover una conexión entre grupos del panel. Crear exige acceso a todas las conexiones; no conecta, pausa ni borra |
webhooks:read | Consultar las suscripciones de webhooks y el historial de sus entregas |
webhooks:write | Crear, modificar y deshabilitar suscripciones, rotar secretos de firma y reenviar entregas |
notta:read | Ver, listar y descargar las facturas y notas ya emitidas |
notta:write | Emitir facturas y notas ante el SII a nombre de la empresa de esta conexión, y reenviar por correo un documento ya emitido. Un documento emitido no se borra: solo se corrige con una nota de crédito |
gmail:readonly | Buscar correos, leer su contenido y pedir un enlace para descargar sus adjuntos en las cuentas de Gmail conectadas. Beta por invitación; se otorga solo nombrándolo |
gmail:send | Enviar correos desde las cuentas de Gmail conectadas, a lo más una vez por clave de idempotencia. Beta por invitación; se otorga solo nombrándolo |
outlook:readonly | Buscar correos, leer su contenido y pedir enlaces de descarga de sus adjuntos en los buzones de Outlook o Microsoft 365 conectados. Beta por organización; se otorga solo nombrándolo |
outlook:send | Enviar correos desde los buzones de Outlook o Microsoft 365 conectados, a lo más una vez por clave de idempotencia. La aceptación del envío no acredita entrega. Beta por organización; se otorga solo nombrándolo |
Cuatro 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
:reades 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. - Los permisos de Gmail y Outlook se otorgan solo nombrándolos.
gmail:readonly,gmail:send,outlook:readonlyyoutlook:sendno entran por*, por un perfil ni por un nivel de consentimiento OAuth, y solo una persona con rol owner o admin puede otorgarlos. Los permisos:readonlyno terminan en:reada propósito: quedan fuera del perfil de solo lectura y del techo de un miembro. La habilitación de la beta por organización y el consentimiento del buzón siguen siendo necesarios.
Los nueve permisos sociales de X, LinkedIn e Instagram también se otorgan sólo nombrándolos por un owner o admin. Identidad, verificación y publicación son independientes. La conexión exige OAuth real del proveedor, beta vigente y permisos efectivos; un comodín, perfil o habilitación de beta no los concede.
Los grupos de conexiones tienen permisos independientes: conexiones:grupos:read para consultar y conexiones:grupos:write para crear y mover. Debes marcarlos por separado; no los incluyen *, los permisos generales de conexiones, los perfiles ni los niveles OAuth. Un miembro puede autorizar la lectura; la escritura requiere owner o admin. El permiso de lectura muestra los nombres de los grupos de la organización, incluidos los vacíos, pero sólo los integrantes que alcanza la clave.
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).
scope no es alcance
scope es el permiso de ejecución («¿puedes llamar esto?»). alcance es un módulo de datos del plano read («¿qué subconjunto sincroniza esta conexión?»). Son ejes independientes: sii:read es un scope; rcv y boletas son alcances. La distinción completa está en Los dos planos.
Conexiones de una clave
Los scopes dicen qué puede hacer una clave. El acceso a conexiones dice sobre cuáles empresas. Lo eliges al crear la clave y lo puedes cambiar después, editándola:
- Todas las conexiones (por defecto). La clave alcanza todas las conexiones de la organización, también las que se conecten después.
- Solo las que elijas. La clave ve y opera únicamente las conexiones marcadas. Sirve cuando una organización reúne las conexiones de varios clientes y cada integración debe tocar solo las suyas.
Una clave limitada a algunas conexiones se comporta así:
- Lo que queda fuera de su lista no existe para ella. Ejecutar una tool sobre otra conexión responde
403 connection_disabled, la misma respuesta que recibe unconnectionIdinexistente.GET /v1/connections,GET /v1/tools,search_docsyconexiones.estado.consultarmuestran solo lo que alcanza. - No crea conexiones. Un enlace de alta,
conexiones.conexion.crearo una carpeta tributaria puntual responden403 forbidden: la conexión nueva no estaría en su lista. Sobre una conexión propia sí puede reconectar, deshabilitar, habilitar o eliminar, si tiene el scope correspondiente. - No usa las rutas que abarcan toda la organización. Webhooks, solicitudes de carpeta tributaria y solicitudes de honorarios responden
403 forbidden. Para esas rutas usa una clave con acceso a todas las conexiones. - La lista no crece sola. Una conexión nueva se agrega editando la clave. Al eliminar una conexión sale de la lista, y una clave que se queda sin conexiones no alcanza ninguna: nunca vuelve a «todas».
Los sistemas que no usan conexión, como los indicadores del Banco Central, siguen disponibles según los scopes de la clave. Cambiar la lista no cambia el valor de la clave y aplica desde la llamada siguiente.
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:
- El cliente descubre los metadatos del recurso protegido (
/.well-known/oauth-protected-resource) y, desde ahí, el authorization server. - Se registra en caliente en
/register(Dynamic Client Registration): sin coordinación previa y sin client secret, porque solo se admiten clientes públicos. - Abre
/authorizecon PKCE S256 obligatorio; una persona inicia sesión, elige la organización y aprueba. - Canjea el código en
/tokeny recibe un access tokenconnect_at_y un refresh tokenconnect_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.
Discovery y challenge no se mezclan
/.well-known/oauth-protected-resource (RFC 9728) es un documento de descubrimiento público que siempre responde 200, sin autenticación. El challenge 401 + WWW-Authenticate vive solo en /mcp y /api/v1/*. Un cliente que recibiera un 401 en el endpoint de metadatos no podría completar el flujo nunca.
Cuándo usar cuál
Las dos superficies aceptan las dos credenciales; la elección real es quién custodia el secreto.
API key (connect_sk_) | OAuth 2.1 (connect_at_ / connect_rt_) | |
|---|---|---|
| Caso natural | Tu backend, scripts y agentes propios, sobre REST o MCP | Un cliente MCP interactivo que una persona conecta |
| Cómo nace | La creas tú en el dashboard | El cliente se registra solo (DCR) y una persona aprueba |
| Autoridad | Los scopes explícitos que marcaste, sobre todas las conexiones o solo las que elijas | Los permisos que pide el cliente, acotados por tu rol en la organización elegida al aprobar, sobre todas las conexiones |
| Actor en la bitácora | agent | user |
| Vida | Hasta revocarla, o el vencimiento que le pongas | El access token vence y el cliente lo renueva con el refresh token |
Próximos pasos
- Tu primera llamada: el quickstart que comprueba una clave nueva con la lista de sus conexiones.
- 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.
Consultar con la API
Lee el registro de ventas del SII de una empresa con una llamada HTTP y tu clave de API, sin instalar nada. Con demo animada del editor y la terminal, y la misma llamada con curl.
Webhooks
Un aviso firmado cuando una sincronización termina o un enlace de conexión se usa, sin sondear. El webhook nunca es load-bearing: el estado real siempre se puede consultar.