Claves de API de la cuenta
Claves para que tu integración continua y tus scripts trabajen con tus aplicaciones, sus fichas y tus empresas de prueba: quién las crea, qué pueden hacer, cómo se usan y cómo se renuevan o se revocan.
Actualizado el . 7 min de lectura
Una clave de API de la cuenta deja que un programa trabaje con tu cuenta de desarrollador sin que nadie inicie sesión: tu integración continua consulta tus aplicaciones, actualiza el borrador de una ficha y sus imágenes, o crea y restablece una empresa de prueba antes de pasar las pruebas. Cada clave actúa en nombre de una persona del equipo y nunca puede más que ella. Se gestionan en Cuenta, Claves de API de la consola.
Lo que hace una clave y lo que hace siempre una persona
Tu integración continua
Con una clave
En la consola
Solo una persona
Crear una aplicación o renovar sus claves fabrica credenciales que seguirían valiendo después de revocar la clave, y enviar a revisión acepta las Normas del catálogo: por eso lo hace una persona. Para lo que quieras hacer hablando, tu asistente de IA tiene su propio servidor, con tus permisos: lo cuenta Conectar tu asistente de IA a la consola.
Quién las gestiona
- La persona titular y Administración ven, crean, cambian, renuevan y revocan las claves de la cuenta.
- Solo la persona titular pone una clave a nombre de otra persona del equipo. Administración crea las suyas, a su nombre.
- Desarrollo, Finanzas y Solo lectura no ven el apartado. Si necesitas una clave para tu integración continua, pídela a la persona titular o a Administración.
- La persona responsable de una clave puede revocarla aunque no gestione las claves.
Lo que puede cada rol está en Equipo y roles.
Crear una clave
Abre Claves de API
En la consola, entra en Cuenta y elige Claves de API. Pulsa Nueva clave.
Ponle un nombre
Uno que diga dónde se usa, como «Integración continua». La descripción es opcional.
Elige la persona responsable
Por defecto eres tú. La clave actúa con los permisos de esa persona: si sale del equipo o se bloquea su acceso, la clave deja de funcionar.
Elige qué puede hacer
Todos los permisos, Solo lectura o Restringido, con los módulos que marques. Lo explica la tabla de abajo.
Decide la caducidad
Sin caducidad, 30, 90 o 180 días, 1 año o una fecha. Si caduca, te avisamos 7 días antes y el día antes: lo cuenta Antes de que caduque.
Crea la clave y cópiala
Pulsa Crear la clave. Si tienes la verificación en dos pasos, escribe tu código. La clave se enseña una sola vez: cópiala y guárdala en el gestor de secretos de tu integración continua antes de pulsar Ya la he guardado.
En Opciones avanzadas está el límite de peticiones por hora: 1.000 si no lo cambias, entre 10 y 10.000.
Qué puede hacer cada clave
Una clave de una cuenta de desarrollador tiene sus propios módulos, distintos de los de una empresa. Con Restringido marcas cada uno; con Todos los permisos tiene los dos enteros, y con Solo lectura, la lectura de las aplicaciones y sus fichas.
| Módulo | Acceso | Qué permite |
|---|---|---|
| Aplicaciones y fichas | developer-apps:read | Consultar tus aplicaciones, sus avisos enviados, sus métricas, sus errores, la comprobación de su conexión, el perfil público, las fichas, su lista «Antes de enviar», sus instalaciones y el hilo de la revisión. |
| Aplicaciones y fichas | developer-apps:write | Lo anterior, y además crear la ficha de una aplicación, guardar su borrador, subir y quitar imágenes, responder a la revisión, cancelar un envío, retirar una ficha del catálogo, volver a publicar la última versión aprobada y cambiar el perfil público. |
| Empresas de prueba | developer-sandboxes:write | Ver, crear, renombrar, restablecer y borrar empresas de prueba, leer sus correos capturados y simular la suscripción de una instalación de prueba. No tiene solo lectura: consultarlas va con este mismo acceso. |
Una clave nunca puede más que su persona responsable. Con Todos los permisos a nombre de alguien de Desarrollo, por ejemplo, la clave hace lo que permite el rol Desarrollo, y nada del equipo ni del dinero.
Trátala como una contraseña
Una clave no pide la verificación en dos pasos: quien la tenga puede usarla. Guárdala en los secretos de tu integración continua, nunca en el código ni en un repositorio, y revócala en cuanto sospeches que se ha filtrado. Una clave sin caducidad vale hasta que la revoques.
Usar la clave
Envía la clave en la cabecera Authorization, con Bearer delante, desde un servidor: UTILIA OS rechaza las peticiones con clave que salen de un navegador. Para comprobar que está bien puesta, pídele sus datos:
curl 'https://os.utilia.ai/api/v2/organization-api-keys/current' \
-H "Authorization: Bearer $UTILIA_API_KEY"La respuesta trae effectivePermissions con sus dos módulos, developer-apps y developer-sandboxes, y lo que puede hoy en cada uno. Las rutas que puedes llamar con ella, recurso a recurso, están en La API de la consola.
Comprobar una clave
La ficha de cada clave, en Cuenta, Claves de API, tiene la sección Comprobar: si funciona, qué puede hacer hoy, qué llamadas se le han rechazado en las últimas 24 horas y quién arregla cada cosa. La propia clave puede pedir lo mismo desde tu integración continua:
/api/v2/organization-api-keys/current/diagnosticsVeredicto, permisos efectivos por módulo, estado de la persona responsable, cupo, llamadas rechazadas y hallazgos con quién los arregla. Solo responde a una clave.
En una cuenta de desarrollador, organization.kind vale developer, plan.modules va vacío porque la cuenta no tiene plan, y permissions.byModule habla solo de developer-apps y developer-sandboxes. Los hallazgos y lo que significa cada uno están en Comprobar una clave: son los mismos, salvo el de módulos fuera del plan, que aquí no sale nunca.
Renovar, cambiar y revocar
Todo se hace desde la ficha de la clave:
- Renovar la clave da un secreto nuevo. La anterior puede seguir valiendo 0, 1, 7 o 30 días para que cambies la clave sin cortes; mientras tanto, Retirar la anterior ya la corta en el acto.
- Editar cambia el nombre, los permisos, la caducidad y el límite. Estrechar no pide nada. Ampliar los permisos y alargar o quitar la caducidad solo lo hacen la persona responsable o la persona titular, con su código de verificación; cambiar de persona responsable también pide el código.
- Revocar corta la clave y la anterior en el acto. Una clave revocada o caducada no vuelve a valer: crea otra.
Antes de que caduque
Si la clave tiene caducidad, su persona responsable y, si es otra, quien la creó reciben un aviso en Avisos de la consola y por correo electrónico: siete días antes (si la creas con menos margen, en la primera hora) y otra vez el día antes, con la fecha y la hora en que deja de valer. El aviso lleva a la ficha de la clave en Cuenta, Claves de API, donde se alarga su caducidad o se renueva. Si quien lo recibe no puede alargarla, el aviso le dice a quién pedírselo. Cuando caduca ya no se puede renovar: hay que crear otra.
Si quitas a una persona del equipo, las claves de las que era responsable se revocan en ese momento, y volver a invitarla no las devuelve: crea otras a nombre de quien siga. Las que creó para otra persona siguen funcionando. Si la persona responsable solo está bloqueada, su clave se detiene hasta que la persona titular la ponga a nombre de otra persona desde su ficha, con Nombrar a otra persona.
Si algo falla
API_KEY_PERMISSION_NOT_GRANTED: la ruta pide algo que la clave no tiene marcado. Amplía sus permisos o crea otra clave.API_KEY_RESPONSIBLE_PERMISSION_MISSING: la clave lo tiene marcado, pero su persona responsable no puede hacerlo con su rol.API_KEY_ROUTE_NOT_AVAILABLE: esa ruta no admite claves, como el equipo, los datos fiscales, los cobros o la vinculación. Lo hace una persona en la consola.APP_CATALOG_HUMAN_SESSION_REQUIREDoSANDBOX_HUMAN_SESSION_REQUIRED: enviar a revisión, cambiar los planes, instalar para probar o abrir una empresa de prueba lo hace una persona.- No ves Claves de API en Cuenta: tu rol no las incluye. Pídeselo a la persona titular o a Administración.
Los demás errores de una petición con clave están en Hacer peticiones con una clave.