Hazlo cuando un sistema de tu organización, como tu CRM o tu historia clínica, va a usar Arbol por su cuenta. Normalmente te lo pide quien desarrolla esa conexión. Una API key es la llave con la que ese sistema entra a Arbol, con los permisos que elijas.
Antes de empezar
- Para crear, rotar y eliminar API keys necesitas el rol Administración de Cuenta, el rol Administración de Raíz, Agenda o Ámbar, o ser el Propietario. Con Consulta de Cuenta puedes verlas, sin cambiarlas.
- Una key solo puede tener permisos que tú tienes.
- Pregúntale a quien la va a usar qué necesita su sistema: en qué aplicaciones, y si solo consulta información o también la cambia. Dale solo eso.
- La key se muestra una sola vez. Decide antes dónde se va a guardar: lo ideal es un gestor de secretos, nunca un correo o un chat.
Pasos
-
En el menú, en Administración, haz clic en API keys.
-
Haz clic en Crear API key. Si todavía no hay ninguna, el botón se llama Crear la primera.
-
En Nombre, escribe qué la va a usar, para reconocerla después. Por ejemplo: «Integración con el CRM». Hasta 60 caracteres.
-
En Permisos, elige para cada grupo Todo o, si el grupo tiene permisos de consulta y de cambio, Solo lectura. Nada aparece cuando ya elegiste algo del grupo y lo desmarca. Para elegir permiso por permiso, despliega el grupo. Arriba, Elegir todo (N) marca todos los que puedes dar y, después, Quitar todo los desmarca. Hay grupos por aplicación, por integración y para Cuenta.
Los permisos que tú no tienes aparecen, pero no se pueden elegir: «No lo tienes, así que tu key tampoco puede tenerlo.».
-
Si los permisos que elegiste llegan a una integración que tiene tu organización, aparece Conexiones y herramientas. Ahí puedes limitar la key dentro de esa integración:
- En Conexiones de y el nombre de la integración, elige Solo algunas y marca las conexiones que puede usar.
- En Herramientas de y el nombre de la integración, elige Solo algunas y marca las herramientas que puede usar.
Lo que dejes en Todas lo deciden sus permisos. Qué son las conexiones y las herramientas está en Ver las integraciones.
-
En Vencimiento, elige la fecha y la hora en que la key deja de funcionar. Por defecto vence en siete días.
-
Haz clic en Crear key.
-
En la ventana Tu API key «…», haz clic en Copiar (dice Copiado cuando la copió) y guárdala donde decidiste. Después haz clic en Listo, ya la guardé.
Qué ves cuando terminas
La key aparece en la lista con su Nombre y su identificador debajo, sus Permisos por aplicación y la fecha en que fue Creada. Si la limitaste, ves además una etiqueta como «SURA: 1 conexión · 3 herramientas». La key en sí no se vuelve a mostrar.
Rotar una key
Rota una key si crees que alguien más pudo verla, o cuando tu organización cambia sus llaves cada cierto tiempo.
-
En API keys, en la fila de la key, abre el menú ⋯ y elige Rotar.
-
Confirma con Rotar.
-
En la ventana La nueva key de «…», cópiala con Copiar, guárdala y haz clic en Listo, ya la guardé.
-
Pon la nueva key en el sistema que la usa.
La nueva key tiene los mismos permisos. La anterior deja de funcionar en unos dos minutos, así que actualiza el sistema enseguida.
Eliminar una key
Elimina una key cuando el sistema que la usaba ya no la necesita.
-
En API keys, en la fila de la key, abre el menú ⋯ y elige Eliminar.
-
Confirma con Eliminar.
Ves el mensaje «Eliminaste «…». Deja de funcionar en unos dos minutos.». No se puede recuperar: los sistemas que la usan pierden el acceso.
Si una key quedó expuesta
Si una key se pegó en un correo, un chat, un documento o un repositorio de código, trátala como comprometida aunque creas que nadie la vio:
- Rótala enseguida si el sistema la sigue necesitando, y pon la nueva en el sistema. La expuesta deja de funcionar en unos dos minutos.
- Elimínala si ya no se usa.
- Borra el mensaje o el archivo donde quedó y avisa a quien administra la seguridad de tu organización.
Una key para todo
Una sola key con Elegir todo, compartida por varios sistemas y guardada en un chat.
Una key por sistema, con lo justo
Una key por sistema, con el nombre de ese sistema, solo los permisos que usa y guardada en un gestor de secretos.
Problemas frecuentes
- Perdí la key o no la copié. No se puede volver a mostrar. Rótala: obtienes una nueva con los mismos permisos.
- Necesito cambiar los permisos de una key. Los permisos de una key no se editan. Crea una nueva con los permisos correctos, ponla en el sistema y elimina la anterior.
- «Una API key no puede tener permisos que tú no tienes.» Elige solo permisos que tienes, o pídele la key a alguien que tenga esos permisos.
- «Elige al menos una, o vuelve a «Todas».» Elegiste Solo algunas sin marcar ninguna.
- No veo el botón Crear API key ni el menú de cada key. Tu rol solo te deja verlas.
- «Escribe un nombre.» o «Usa como máximo 60 caracteres.» El Nombre es obligatorio y tiene hasta 60 caracteres.
- «Esa API key ya no existe. Actualiza la página.» Otra persona la eliminó o la rotó mientras tanto. Recarga la página.
Para desarrolladores
Cómo se envía una API key en cada llamada, qué hacen los permisos y qué otras credenciales existen está en Autenticación.