La API de gestión de claves
Las rutas con las que la pantalla Claves de API lista, crea, cambia, renueva y revoca claves, con la sesión de una persona, y sus errores.
Actualizado el . 5 min de lectura
Incluido en todos los planes. Ver precios
La pantalla Ajustes, Claves de API usa estas rutas, siempre con el token de sesión de una persona (Authorization: Bearer <token>) y sus permisos. Sirven para automatizar la gestión de las claves desde una herramienta interna, no para el programa que usa la clave: una clave no crea, cambia, renueva ni revoca claves, y la única de estas rutas que le responde es GET /current.
Las rutas
| Método y ruta | Para qué | Permiso |
|---|---|---|
GET /api/v2/organization-api-keys | Lista las claves de la organización | Ver o gestionar las claves de API |
GET /api/v2/organization-api-keys/:id | Ficha, con los permisos efectivos de hoy | Ver o gestionar las claves de API |
GET /api/v2/organization-api-keys/:id/usage | Uso de 24 horas y 7 días y rutas usadas | Ver o gestionar las claves de API |
GET /api/v2/organization-api-keys/catalog | Módulos que se pueden marcar, recortados por el plan | Gestionar las claves de API |
GET /api/v2/organization-api-keys/responsible-candidates | Personas que puedes nombrar responsables | Gestionar las claves de API |
POST /api/v2/organization-api-keys | Crea una clave y devuelve el secreto una sola vez | Gestionar las claves de API |
PATCH /api/v2/organization-api-keys/:id | Cambia nombre, descripción, límite, caducidad, permisos o responsable | Gestionar las claves de API |
POST /api/v2/organization-api-keys/:id/rotate | Renueva, con graceDays 0, 1, 7 o 30, y devuelve el secreto nuevo una sola vez | Gestionar las claves de API, y ser su responsable o Super Administrador |
POST /api/v2/organization-api-keys/:id/end-transition | Retira ya la clave anterior | Gestionar las claves de API |
POST /api/v2/organization-api-keys/:id/revoke | Revoca la clave, con un motivo opcional en reason | Gestionar las claves de API, o ser su responsable |
Las lecturas aceptan también INTEGRATIONS_APPS_VIEW, el permiso con el que se veía antes esta pantalla. Cada clave lleva su estado en status, que se explica en Estados de una clave.
Qué pide cada acción
Además del permiso, algunas acciones necesitan Integraciones en el plan, no se pueden hacer con la organización en modo restringido o piden la verificación en dos pasos:
Qué pide cada acción
| Acción | Integraciones en el plan | Sin modo restringido | Código de dos pasos |
|---|---|---|---|
| Listar, ver la ficha y el uso | No | No | No |
| Consultar el catálogo de módulos | Sí | No | No |
| Crear una clave | Sí | Sí | Sí |
| Renombrar, cambiar el límite o recortarTambién adelantar la caducidad o ponérsela a una clave que no la tenía. | Sí | No | No |
| Ampliar, alargar o quitar la caducidadTambién cambiar de persona responsable. | Sí | Sí | Sí |
| Renovar | Sí | Sí | Sí |
| Retirar la anterior ya | No | No | No |
| Revocar | No | No | No |
- Listar, ver la ficha y el usoNo
- Consultar el catálogo de módulosSí
- Crear una claveSí
- Renombrar, cambiar el límite o recortarTambién adelantar la caducidad o ponérsela a una clave que no la tenía.Sí
- Ampliar, alargar o quitar la caducidadTambién cambiar de persona responsable.Sí
- RenovarSí
- Retirar la anterior yaNo
- RevocarNo
- Listar, ver la ficha y el usoNo
- Consultar el catálogo de módulosNo
- Crear una claveSí
- Renombrar, cambiar el límite o recortarTambién adelantar la caducidad o ponérsela a una clave que no la tenía.No
- Ampliar, alargar o quitar la caducidadTambién cambiar de persona responsable.Sí
- RenovarSí
- Retirar la anterior yaNo
- RevocarNo
- Listar, ver la ficha y el usoNo
- Consultar el catálogo de módulosNo
- Crear una claveSí
- Renombrar, cambiar el límite o recortarTambién adelantar la caducidad o ponérsela a una clave que no la tenía.No
- Ampliar, alargar o quitar la caducidadTambién cambiar de persona responsable.Sí
- RenovarSí
- Retirar la anterior yaNo
- RevocarNo
El código va en el cuerpo, en twoFactorCode (seis dígitos o un código de respaldo) o, si se aprobó desde la aplicación móvil, en twoFactorApprovalId. Ampliar, alargar o quitar la caducidad y renovar solo lo hacen la persona responsable de la clave o un Super Administrador, y nombrar responsable a otra persona, solo un Super Administrador.
Alargar la caducidad
Es lo que hace falta cuando llega el aviso de que una clave caduca pronto y el programa la sigue necesitando. Se manda la fecha nueva en expiresAt y, si tienes la verificación en dos pasos activa, el código:
curl -X PATCH 'https://os.utilia.ai/api/v2/organization-api-keys/cm2k8x0ab0001qz7f3d4e5f6g' \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"expiresAt": "2027-04-30T23:59:59.000Z", "twoFactorCode": "123456"}'Responde 200 con la clave y su expiresAt nuevo, y los avisos de caducidad se vuelven a programar para esa fecha. Estos son los campos que acepta PATCH, todos opcionales:
- namestring
- Nombre de la clave, de hasta 120 caracteres.
- descriptionstring | null
- Descripción, de hasta 500 caracteres. null o una cadena vacía la borran.
- rateLimitPerHournumber
- Peticiones por hora, entre 10 y 10.000.
- expiresAtstring | null
- Nueva caducidad, en ISO 8601 y en el futuro. null la quita. Sin el campo, no cambia.
- permissionMode'ALL' | 'READ_ONLY' | 'RESTRICTED'
- Modo de la clave.
- moduleAccessstring[]
- Con RESTRICTED, un acceso por módulo: 'modulo:read' o 'modulo:write'.
- responsibleUserIdstring
- Nueva persona responsable. Solo un Super Administrador nombra a otra persona.
- twoFactorCodestring
- Código de la verificación en dos pasos de quien hace el cambio, cuando hace falta.
- twoFactorApprovalIdstring
- Confirmación aprobada desde la aplicación móvil, en lugar del código. Vale una sola vez y para esta misma acción.
Una clave caducada ya no se puede alargar: responde 409 API_KEY_NOT_MODIFIABLE y hay que crear otra.
Errores de la gestión
Además de los errores de permiso, plan y modo restringido de cualquier ruta, estas responden con estos:
| errorCode | HTTP | Qué pasa |
|---|---|---|
API_KEY_MODULE_REQUIRES | 400 | Un módulo necesita otro en la misma clave, como Stripe, que necesita «Finanzas: leer». |
API_KEY_MODULE_ACCESS_INVALID | 400 | Los módulos marcados no son válidos: un acceso mal escrito, un módulo repetido o «escribir» en uno que solo se consulta. |
RESPONSIBLE_SELF_ONLY | 403 | Solo un Super Administrador nombra responsable a otra persona, y solo la persona responsable o un Super Administrador renuevan, amplían o alargan una clave. |
RESPONSIBLE_NOT_ELIGIBLE | 409 | La persona elegida no está activa en tu organización. |
API_KEY_NOT_MODIFIABLE | 409 | La clave está revocada o caducada: no se cambia ni se renueva. Crea otra. |
ROTATION_IN_PROGRESS | 409 | Ya hay una renovación en transición. Retira antes la anterior. |
NO_TRANSITION_IN_PROGRESS | 409 | No hay ninguna clave anterior que retirar. |
API_KEY_CHANGED_MEANWHILE | 409 | Otra persona cambió la clave a la vez. Vuelve a abrirla y repite el cambio. |
TWO_FACTOR_REQUIRED | 401 | Falta el código de la verificación en dos pasos de quien hace el cambio. Repite la petición con él. |
ORGANIZATION_RESTRICTED | 403 | La organización está en modo restringido: no se puede crear, renovar, ampliar ni alargar una clave. |
ORG_API_KEYS_DISABLED | 403 | Las claves de API de la organización no están activadas en el servidor: no se pueden crear ni renovar. |
API_KEY_REQUIRED | 403 | GET /current se llamó sin una clave. |
Los errores que recibe el programa que usa la clave están en Errores de una petición.
Siguiente paso
Ponlo en práctica
Lo encontrarás en Claves de API. Para abrirlo, entra con tu cuenta de UTILIA OS.