# 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. 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** ## Con una clave (Tu integración continua) Consultar tus aplicaciones, sus errores, sus métricas y sus avisos; preparar fichas, sus imágenes y los mensajes con la revisión; crear, restablecer y borrar empresas de prueba y leer sus correos. ## Solo una persona (En la consola) Enviar una ficha a revisión, poner precios y planes, todo lo del dinero, crear o cambiar aplicaciones y sus claves, abrir una empresa de prueba, instalar para probar, el equipo, los datos fiscales y la vinculación con tu empresa. 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](https://os.utilia.ai/docs/developers/console/mcp). ## 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](https://os.utilia.ai/docs/developers/console/team). ## Crear una clave 1. **Abre Claves de API** En la consola, entra en **Cuenta** y elige **Claves de API**. Pulsa **Nueva clave**. 2. **Ponle un nombre** Uno que diga dónde se usa, como «Integración continua». La descripción es opcional. 3. **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. 4. **Elige qué puede hacer** **Todos los permisos**, **Solo lectura** o **Restringido**, con los módulos que marques. Lo explica la tabla de abajo. 5. **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](#antes-de-que-caduque). 6. **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. > **Atención: 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: ```bash 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](https://os.utilia.ai/docs/developers/console/developer-api). ## 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: **`GET /api/v2/organization-api-keys/current/diagnostics`** Veredicto, 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](https://os.utilia.ai/docs/developers/organization-api-keys/diagnostics): 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_REQUIRED`** o **`SANDBOX_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](https://os.utilia.ai/docs/developers/organization-api-keys/first-request#errores-de-una-petición).