Credenciales
7 min de lectura
Credenciales es el almacén cifrado de secretos de la organización. Úsalo para contraseñas, claves API, cuentas, claves SSH y códigos de doble factor que los agentes necesiten utilizar.
No compartas secretos en un chat
No pegues claves ni contraseñas en mensajes a un agente. Guárdalas como credenciales para mantenerlas cifradas, asignadas y auditables.
Crear una credencial
Una credencial reúne los datos que un agente necesita para acceder a un mismo servicio. Por ejemplo, puedes crear una para «GitHub de producción» con un usuario y un token, o una para un servidor con su dirección, usuario, clave SSH y código de doble factor.
Identifica el acceso
Ponle un nombre que explique el servicio y su uso. Evita nombres genéricos como «token» o «cuenta nueva».
Añade solo los campos necesarios
Combina los tipos de campo que requiera ese acceso: usuario, contraseña, URL, clave API, clave SSH, código de doble factor o nota. La nota sirve para instrucciones no sensibles; los valores secretos van en sus campos específicos.
Elige si es privada o de equipo
Arriba del formulario, Privada la deja solo para ti y los operadores que añadas; De equipo, para todos los operadores, también los que entren después. Por defecto es privada.
Asígnala a sus agentes
En la pestaña Agentes marca qué agentes pueden usarla. Un agente asignado la usa durante su trabajo sin que el secreto aparezca en el chat.
Las revelaciones de valores están controladas por permisos y quedan registradas en la actividad de la organización.
Quién puede usarla
Cuando un operador habla con un agente, el agente solo usa la credencial si ese operador tiene acceso a ella: porque es de equipo, porque está en su lista o porque es propietario o administrador de la organización y la credencial no es privada de otra persona. Si no, para ese agente la credencial no existe en esa conversación.
Los propietarios y administradores ven todas las credenciales privadas: su nombre, su descripción, sus destinos, quién las tiene y qué agentes las usan. Si no están en su lista, no ven sus valores ni pueden editarlas, asignarlas o usarlas. Sí pueden archivarlas, eliminarlas o quitárselas a un agente.
En la pestaña Operadores de cada credencial das a cada persona uno de estos niveles:
| Nivel | Qué permite |
|---|---|
| Sin acceso | Nada. En una credencial de equipo no se puede elegir: todos tienen al menos Usar. |
| Usar | Un agente puede usarla en las conversaciones de esa persona. Ella no la ve en el panel ni revela sus valores. |
| Gestionar | Además, verla, revelar sus valores, editarla y asignarla. |
Quien crea una credencial privada entra con Gestionar. Una tarea programada usa las credenciales de quien la creó. Cuando un agente consulta a otro por algo que le ha pedido una persona de tu equipo, el segundo agente usa solo las credenciales a las que esa persona tiene acceso, también si la consulta pasa por varios agentes. Los webhooks, las tareas sin creador y las consultas entre agentes sin una persona concreta detrás solo usan las credenciales de equipo. Las cuentas conectadas, como GitHub o Google, funcionan igual.
Conversaciones con clientes
Por defecto una credencial es Interna: un agente no puede usarla cuando habla con un cliente, alguien de fuera de tu organización que le escribe por un canal externo como el correo o WhatsApp. En esas conversaciones, la credencial no está disponible para él.
Si un agente necesita una clave para atender a clientes, por ejemplo la API de pedidos de tu tienda, elige Externo al crearla o, si ya existe, en su pestaña Operadores. Una credencial externa es siempre de equipo: elegir Externo la pasa a De equipo, y volverla Privada la deja en Interno. Deja como internas las que dan acceso a sistemas internos: servidores, bases de datos o cuentas de administración.
El cambio queda registrado en la actividad de la organización.
Esta opción se aplica también cuando el agente consulta a otro agente por algo que le ha pedido un cliente: el segundo agente responde con los mismos límites.
Destino
El Destino de una credencial son las direcciones donde se puede usar: api.stripe.com, https://panel.acme.com. El agente la usa solo ahí; enviada a otro sitio, Kujira no la entrega. Así una instrucción colada en una página o un correo no puede llevarse la clave a otra parte. Un dominio sin subdominio, como acme.com o *.acme.com, vale para todo el dominio. Una dirección con subdominio vale solo para ella y su www.: tienda.acme.com sirve en www.tienda.acme.com, pero no en crm.acme.com. En dominios que comparten muchos usuarios, como github.com, google.com o github.io, vale solo la dirección exacta.
Si una credencial no tiene destino, o el agente la necesita en un sitio que no es el suyo, te lo pide con una tarjeta que enseña la dirección:
| Opción | Qué hace |
|---|---|
| Siempre | Guarda esa dirección como destino de la credencial. No vuelve a preguntar. |
| Solo esta vez | La deja usar ahí durante una hora, en esa conversación. La credencial no cambia. |
| No | No se usa. El agente no vuelve a pedirlo en esa conversación. |
La decide quien habla con el agente, si tiene acceso a la credencial. Siempre no aparece si la dirección no coincide con lo que ya se sabe de la credencial —sus otros destinos o su campo URL—, si es una IP o si es un servicio que recoge lo que se le envía. Para guardarla igualmente, añádela tú en el campo Destino de la credencial.
En una credencial de correo (SMTP), el destino se parte en dos: el Servidor, que es a donde va la contraseña, y los Destinatarios, a quién puede escribir el agente con ella. Pon direcciones (ana@acme.com) o dominios enteros (*@acme.com). Si dejas Destinatarios vacío, puede escribir a cualquiera. Si pones alguno, un correo a otra dirección no sale, tampoco en copia ni en copia oculta.
Las claves SSH y las VPN no necesitan destino: la clave SSH solo firma, y la VPN llega a su propia red.
Leer correo (IMAP)
Una credencial con usuario y contraseña de una cuenta de correo deja al agente leer la bandeja: buscar, leer mensajes, descargar adjuntos, marcarlos como leídos y moverlos de carpeta. No puede borrar. Pon en el destino el servidor IMAP (imap.gmail.com) y, si la credencial no lo tiene en otro campo, añade uno llamado imap_host con esa dirección. En Gmail la contraseña tiene que ser una contraseña de aplicación.
Cuentas de servicio de Google
Para que un agente use Sheets, Drive o Gmail con una cuenta de servicio, pega el fichero JSON que descargaste de Google en un campo de tipo nota y añade googleapis.com como destino. El agente nunca ve la clave: Kujira la usa para pedir a Google un acceso temporal en cada petición.
Añade además dos campos de texto, porque la credencial decide qué puede hacer el agente con la clave:
| Campo | Qué pones |
|---|---|
scopes | Los permisos de Google que puede pedir, separados por espacios, por ejemplo https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive. Sin este campo solo puede pedir cloud-platform. |
subject | El correo en cuyo nombre actúa, si usas la delegación de dominio de Google Workspace (reservas@tuempresa.com). Sin este campo actúa como la propia cuenta de servicio. |
El agente puede pedir menos de lo que lista la credencial, nunca otra cosa. Para actuar en nombre de alguien, la delegación de dominio tiene que estar autorizada en la consola de administración de Google Workspace para esos mismos permisos.
Claves SSH y doble factor
Para una clave SSH, el panel puede generar un par Ed25519: la clave privada se guarda cifrada y la pública se puede copiar al sistema de destino.
Los campos de doble factor generan el código temporal cuando se necesitan. El agente puede utilizarlo sin tener que publicar el secreto base en una conversación.
Uso en tareas programadas
Las tareas de script pueden recibir credenciales como variables de entorno durante la ejecución. No se escriben en el disco del agente. Cada campo utiliza su etiqueta en mayúsculas; un campo de doble factor proporciona el código temporal vigente.
Consulta Tareas programadas para configurar este tipo de automatización.
Mantenimiento
Las credenciales archivadas pueden recuperarse cuando las necesites. Revisa las que no tienen agentes asignados para retirar accesos que ya no sean necesarios.
Permisos
El acceso a las credenciales se divide para que consultar una ficha no implique necesariamente revelar su secreto. Además de estos permisos, para ver o revelar una credencial hace falta el nivel Gestionar en ella.
| Acción | Permiso |
|---|---|
| Consultar la ficha y sus asignaciones | credential.view |
| Crear o modificar una credencial | credential.edit |
| Archivar o eliminar una credencial | credential.delete |
| Revelar un valor secreto | credential.reveal |
| Gestionar quién puede usar o gestionar la credencial | credential.grant |