# 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.

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 las únicas de estas rutas que le responden son `GET /current` y `GET /current/diagnostics`, que solo hablan de ella.

## 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/:id/diagnostics` | Veredicto y hallazgos, los mismos que obtiene la clave en [Comprobar una clave](https://os.utilia.ai/docs/developers/organization-api-keys/diagnostics) | 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](https://os.utilia.ai/docs/developers/organization-api-keys/expiry-renewal-revocation#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, el uso y la comprobación | 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 recortar (También adelantar la caducidad o ponérsela a una clave que no la tenía.) | Sí | No | No |
| Ampliar, alargar o quitar la caducidad (También cambiar de persona responsable.) | Sí | Sí | Sí |
| Renovar | Sí | Sí | Sí |
| Retirar la anterior ya | No | No | No |
| Revocar | No | No | No |

_Una marca es un requisito. El código solo se pide a quien tiene activa la verificación en dos pasos._

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:

```bash
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:

| Nombre | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `name` | `string` | No | Nombre de la clave, de hasta 120 caracteres. |
| `description` | `string \| null` | No | Descripción, de hasta 500 caracteres. null o una cadena vacía la borran. |
| `rateLimitPerHour` | `number` | No | Peticiones por hora, entre 10 y 10.000. |
| `expiresAt` | `string \| null` | No | Nueva caducidad, en ISO 8601 y en el futuro. null la quita. Sin el campo, no cambia. |
| `permissionMode` | `'ALL' \| 'READ_ONLY' \| 'RESTRICTED'` | No | Modo de la clave. |
| `moduleAccess` | `string[]` | No | Con RESTRICTED, un acceso por módulo: 'modulo:read' o 'modulo:write'. |
| `responsibleUserId` | `string` | No | Nueva persona responsable. Solo un Super Administrador nombra a otra persona. |
| `twoFactorCode` | `string` | No | Código de la verificación en dos pasos de quien hace el cambio, cuando hace falta. |
| `twoFactorApprovalId` | `string` | No | 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](https://os.utilia.ai/docs/developers/organization-api-keys/first-request#errores-de-una-petición).

## Siguiente paso

- [Crear y gestionar claves de API](https://os.utilia.ai/docs/guides/security/api-keys): Las mismas acciones desde la pantalla, paso a paso.