Autenticación y keys
Todas las rutas /v1/* necesitan una API key de Quipua. Las keys empiezan por ci_ y pertenecen a un equipo de tu empresa: el consumo se descuenta del saldo de la empresa y cuenta para el presupuesto de ese equipo.
Cómo enviar la key
Quipua acepta las dos formas que usan los SDK oficiales:
| Cabecera | La usa |
|---|---|
Authorization: Bearer ci_live_xxx | SDK de OpenAI y casi todos los clientes |
x-api-key: ci_live_xxx | SDK de Anthropic |
Si llegan las dos, manda Authorization. Sin key, la respuesta es 401 missing_api_key; con una key desconocida o revocada, 401 invalid_api_key.
Trata la key como una contraseña: guárdala en una variable de entorno o un gestor de secretos y no la pongas en el código del navegador ni en una app móvil. Quipua sólo guarda un resumen (hash) de la key; si la pierdes, crea otra.
Crear una key
Las keys se crean en el panel, en Keys, y se asignan a un equipo. Al crearla puedes fijar:
| Opción | Qué hace | Error si se supera |
|---|---|---|
| Modelos permitidos | Lista de modelos que puede usar la key. Fuera de ella, la petición se rechaza (también con auto, que sólo elige entre los permitidos). | 403 model_not_allowed |
| Peticiones por minuto | Límite propio de la key. Si no lo fijas, 60 peticiones/minuto. | 429 rate_limited |
| Límite de gasto | Importe en USD por día, semana, mes o total (ver abajo). | 403 key_limit_exceeded |
| Caducidad | Fecha a partir de la cual la key deja de funcionar. | 401 key_expired |
| Tope de contexto | Entrada máxima estimada por petición, en tokens. | 413 context_too_large |
| Memoria | Qué memoria de la empresa recibe la key: de empresa y equipo, de dirección o ninguna (ver Memoria). | — |
Límite de gasto por key
El límite se comprueba antes de cada petición con lo gastado en el periodo más lo que la key tiene reservado en peticiones en curso. Si la petición podría pasarse, se rechaza con 403 key_limit_exceeded y un mensaje que dice cuánto queda. Los periodos son naturales: el día, la semana (desde el lunes), el mes o todo el historial de la key.
Caducidad y rotación
Puedes rotar una key desde el panel: se crea una key nueva con la misma configuración (equipo, modelos, límites y caducidad) y la anterior sigue funcionando durante un periodo de gracia de 1 hora, 24 horas o 7 días, para que te dé tiempo a desplegar la nueva. Pasado ese plazo, la anterior responde 401 key_expired y queda revocada.
Estados de una key
| Estado | Qué pasa | Respuesta |
|---|---|---|
| Activa | Funciona con normalidad. | — |
| Caducada | Pasó su fecha de caducidad o el plazo de gracia de una rotación. | 401 key_expired |
| Revocada | La revocó tu empresa o Quipua. Es definitivo. | 401 invalid_api_key |
| Suspendida | Quipua la ha suspendido de forma temporal (por ejemplo, ante un patrón de uso anómalo). | 403 key_suspended |
Si la organización no está activa (alta pendiente o suspendida), todas sus keys responden 403 organization_not_active.
Buenas prácticas
- Una key por aplicación o servicio, para ver el gasto de cada uno por separado y poder revocarla sin afectar al resto.
- Pon un límite de gasto a las keys que usen terceros o procesos automáticos.
- Limita los modelos permitidos si una aplicación sólo necesita uno.
- Rota las keys periódicamente y siempre que alguien con acceso deje el equipo.