Credenciales — Referencia Técnica
Esta página describe cómo funcionan las credenciales por debajo de la interfaz, en términos técnicos, para desarrolladores y usuarios con perfil técnico. Se centra en el modelo y en el comportamiento observable, no en detalles de implementación.
Modelo de arquitectura
Una credencial es un registro con nombre que contiene los secretos que una herramienta o un canal necesitan para llamar a un servicio externo. Los agentes nunca ven los secretos en bruto — solo ven una referencia normalizada ("usa la credencial N"), y la plataforma sustituye los valores secretos en el momento de la solicitud saliente.
Cada credencial tiene dos partes:
- Un registro principal — la identidad visible para el usuario: etiqueta, dueño, familia de autenticación, proveedor, estado.
- Un registro hijo específico del tipo — los valores secretos en sí, cifrados en reposo, legibles solo por el entorno de ejecución de la herramienta en el momento de la solicitud.
Esta separación mantiene el historial del agente y el listado de credenciales libres de secretos, incluso cuando hay varias credenciales para el mismo proveedor.
Familias de autenticación
Las credenciales se agrupan por la forma de la autenticación que el servicio externo requiere, no por proveedor. Cinco familias cubren prácticamente cualquier API pública:
| Familia | Qué guarda | Uso en la solicitud |
|---|---|---|
| basic | Usuario + contraseña | Encabezado Authorization: Basic … |
| bearer | Un token secreto de larga duración | Encabezado Authorization: Bearer … |
| apikey | Una clave estática | Un encabezado o un parámetro de consulta, según los documentos del servicio |
| oauth2 | Una autorización de larga duración firmada por el proveedor | Encabezado Authorization refrescado automáticamente al acercarse a su vencimiento |
| thirdparty | Un inicio de sesión nativo de la plataforma (p. ej., Meta/Facebook para WhatsApp, Instagram, Messenger) | El token firmado específico de la plataforma que el canal espera |
Modelo de almacenamiento
- El registro principal guarda la etiqueta, la familia, el proveedor, el dueño y el estado (activa / vencida / deshabilitada). No guarda el secreto.
- El registro hijo guarda los valores secretos específicos de la familia, cifrados en reposo.
- Una credencial puede compartirse entre muchas herramientas y canales — hay un único secreto guardado, usado por muchos consumidores.
- Cuando se elimina una credencial, cada herramienta y canal que la usaba se queda sin acceso; la plataforma muestra un error claro en lugar de fallar en silencio.
El entorno del agente solo guarda el ID del registro principal. El registro hijo se lee al vuelo cuando una solicitud está a punto de salir de la plataforma.
Flujo de inicio de sesión OAuth
Para credenciales oauth2, el usuario inicia sesión en el servicio externo dentro de una ventana emergente. La experiencia visible es "iniciar sesión con Google / Microsoft / Notion / etc." — no hay IDs de cliente, secretos ni direcciones de redirección que pegar.
- La autorización es de larga duración — el usuario no tiene que iniciar sesión en cada uso.
- Cuando la autorización se acerca a su vencimiento, la plataforma la refresca en segundo plano para que las llamadas sigan funcionando.
- Si un refresco es rechazado (revocado en el proveedor), la credencial queda marcada como vencida y se le pide al usuario que vuelva a conectarla.
thirdparty (inicio nativo de Meta) usa la misma forma de ventana emergente, pero produce un token firmado específico de Meta que los canales de WhatsApp, Instagram y Messenger usan directamente.
Flujo de Credenciales con IA
Cuando un usuario elige un servicio poco familiar, un asistente de IA configura la credencial siguiendo un ciclo fijo:
- La investigación es una lectura corta y automatizada de los documentos públicos del proveedor — sin acceso a paneles privados.
- Los pasos guiados se producen una vez que la IA ha identificado la familia de autenticación. Están en lenguaje claro ("En tu cuenta, ve a Ajustes → Claves de API, pulsa Crear, copia la clave, pégala aquí").
- El paso de conectar es el único lugar donde se introducen secretos. Se cifran antes de guardarse y nunca se devuelven al usuario.
- La verificación hace una llamada real a un endpoint de solo lectura seguro; un fallo retrocede al paso anterior para que el usuario corrija un error de tipeo.
El mismo flujo funciona para configurar una sola credencial o un lote de varias a la vez.
Cómo una herramienta consume una credencial en tiempo de ejecución
Cuando un agente está por llamar a una herramienta que usa una credencial, la plataforma:
- Busca el registro principal por ID y confirma que sigue activa.
- Lee y descifra el registro hijo al vuelo.
- Sustituye el secreto en el lugar correcto para la familia (encabezado, parámetro de consulta o token firmado).
- Envía la solicitud al servicio externo.
- Descarta el secreto descifrado de la memoria una vez completada la solicitud.
- El agente nunca ve el secreto en su prompt ni en su entorno de ejecución.
- Los registros y trazas guardan el ID de la credencial, nunca el valor del secreto.
- Una llamada fallida devuelve un error normal al agente; el agente decide si reintenta o muestra el error.
Credenciales nativas (Meta)
WhatsApp, Instagram y Messenger usan una única credencial nativa de plataforma firmada por Facebook. Esta credencial cubre los tres canales y se crea con una ventana emergente dedicada (no con el flujo OAuth genérico) porque el proveedor emite una forma de token específica de Meta, no estándar.
Como cada canal solo puede asociar una credencial nativa a la vez, un número de WhatsApp Business, una cuenta de Instagram o una Página de Messenger se conecta a un agente.
Límites y garantías
- Una credencial pertenece a un usuario y solo es visible para ese usuario (y compartidas explícitas).
- Los valores secretos están cifrados en reposo y se descifran solo en el momento de una solicitud saliente.
- Una credencial puede reutilizarse en cualquier número de herramientas y canales — hay un solo secreto guardado por credencial, sin importar cuántos consumidores la usen.
- El agente solo guarda el ID de la credencial, nunca el secreto.
- Las credenciales vencidas o revocadas muestran un aviso claro para volver a conectar en lugar de fallar en silencio.
Qué sigue
- Tipos de credenciales — las cinco familias en lenguaje sencillo
- Credenciales con IA — el flujo de configuración guiado por IA
- Credenciales Meta — el inicio de sesión para WhatsApp / Instagram / Messenger