Documentación
API de gestión
Una clave de gestión permite que tus propios sistemas creen, agrupen, limiten y revoquen las claves de API de tu cuenta, y lean lo que gastaron, mediante la API. No puede llamar a un modelo.
Para qué sirve
Algunas integraciones dan a cada uno de sus clientes, equipos o usuarios una clave de API propia, reúnen las claves de cada cliente en un grupo, limitan lo que puede gastar un grupo y consultan el coste por clave o por grupo. En la página Claves de API eso funciona bien con pocas claves. Con más, una clave de gestión permite que un script o tu propia herramienta de administración haga lo mismo mediante la API.
Una clave de gestión es una credencial distinta de una clave de API. No se acepta donde se acepta una clave de API: no puede llamar a /v1/chat/completions, /v1/messages ni a ninguna otra ruta de modelo. Solo funciona en /v1/management/, y allí no funciona una clave de API.
Crea una clave de gestión
- Abre la página Claves de API y baja hasta el final. En «Claves de gestión», elige «Nueva clave de gestión». El bloque permanece plegado hasta que lo abres.
- Ponle un nombre a la clave, por ejemplo sincronización de facturación, para que la página pueda indicar qué programa hizo cada cambio.
- Introduce las direcciones desde las que se puede llamar, una por línea: una dirección única como 203.0.113.7 o un rango como 203.0.113.0/24. Sin lista de direcciones permitidas, cualquiera que tenga la clave puede usarla, y el cuadro de diálogo te avisa si dejas la lista vacía.
- Copia la clave cuando se muestre. Solo se muestra una vez: Kunavo guarda únicamente un hash.
Una cuenta puede tener dos claves de gestión activas a la vez. Revoca una para dejar sitio a otra.
Llámala
Envía la clave como token Bearer a https://api.kunavo.com/v1/management. Las claves de gestión no se aceptan desde un navegador: sus respuestas no incluyen cabeceras CORS, así que una página de otro sitio no puede llamarlas. Una clave debe estar en tu servidor, nunca en código de front-end.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Las respuestas son JSON. Los errores tienen la misma forma que en el resto de la API: un objeto error con un message, un type, un code y, cuando procede, el param que es incorrecto. Estos son los estados que encontrarás:
| Estado | Qué significa |
|---|---|
401 | La clave falta, está mal escrita o revocada, o su cuenta está suspendida o en revisión. |
403 | La clave tiene una lista de IP permitidas y la solicitud llegó desde una dirección que no está en ella. |
404 | El grupo o la clave no existe, está eliminado o pertenece a otra cuenta. Los tres casos responden igual, así que un id de otra cuenta no revela nada. |
409 | El cambio entra en conflicto con el estado de la cuenta: un nombre de grupo ya en uso, una clave revocada, o la cuenta en su tope de 500 claves activas. |
429 | Esta clave ha hecho 60 solicitudes en el último minuto. La cabecera Retry-After indica cuántos segundos esperar. |
Grupos
GET /v1/management/groups lista los grupos de la cuenta, con el límite mensual de cada uno y cuántas claves activas contiene. POST crea uno, con un monthly_limit_usd opcional; un nombre ya en uso devuelve un 409. PATCH /v1/management/groups/{id} cambia el nombre o el límite: envía null para no tener límite y 0 para pausar todas las claves del grupo sin revocar ninguna. DELETE elimina un grupo, y sus llamadas conservan su nombre en la página Uso. Sus claves siguen activas y quedan sin grupo, salvo que añadas ?revoke_keys=true, que también las revoca.
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001", "monthly_limit_usd": 50}'Claves
GET /v1/management/keys lista las claves, de la más reciente a la más antigua. Una página contiene 50 claves, y limit lo eleva a 100. status es active por defecto, o revoked o all, y group_id limita la lista a un grupo. Cuando has_more es true, pasa next_after como after para leer la página siguiente. El texto sin formato de una clave nunca se lista.
POST /v1/management/keys crea una clave con un nombre y, opcionalmente, un group_id, un monthly_limit_usd y un ip_allowlist. La respuesta incluye el texto sin formato en su campo key, una sola vez. Un POST repetido crea una segunda clave, así que antes de reintentar uno, lista las claves y busca su nombre.
curl https://api.kunavo.com/v1/management/keys \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'PATCH /v1/management/keys/{id} cambia el nombre, el grupo, el límite o la lista de permitidas de una clave; un group_id de null la saca de su grupo. DELETE la revoca. Revocar una clave que ya está revocada no es un error. Una clave revocada no se puede modificar.
curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"Uso
GET /v1/management/usage informa del uso de toda la cuenta durante hasta 90 días UTC, igual que GET /v1/usage informa del de una clave. group_by admite cualquier combinación de group, api_key, model y day, y por defecto es api_key. Las cifras significan lo mismo que en la página Uso: una llamada cuenta en el grupo en el que estaba su clave cuando se hizo, una llamada fallida no cuesta nada, y el total de un periodo coincide al céntimo con la exportación CSV de los mismos días. group_id y api_key_id limitan el informe a un grupo o a una clave.
curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"end_date posterior a hoy se interpreta como hoy, y la respuesta devuelve la fecha final que usó.Protégela
- Define una lista de direcciones permitidas. Una clave que solo funciona desde las direcciones de tu servidor vale poco para quien la robe.
- Guarda la clave en un almacén de secretos del servidor que ejecuta tu herramienta. No la pongas nunca en un navegador, una app móvil ni un repositorio.
- Si se filtra, revócala al final de la página Claves de API, o con
DELETEsobre ella. El cuadro de revocación también puede revocar las claves que creó esa clave. - Cada cambio que la clave hace mediante la API aparece en «Claves de gestión» de la página Claves de API, con su hora, la dirección de origen y la clave que lo hizo: los últimos 50 cambios. Los cambios hechos a mano en esa página no aparecen.
- Una clave deja de funcionar por sí sola cuando su cuenta se suspende o se pone en revisión, y cuando se revoca.
Una clave de gestión puede hacer 60 solicitudes por minuto. Haz una solicitud por cada cambio, y lee una lista por páginas en lugar de clave por clave.
Relacionado
Los grupos, sus límites mensuales y la forma de contar sus cifras se explican en la página de grupos de claves. Las cifras de uso son las mismas que en la página Uso.