Virtual keys

Una virtual key es la credencial que envían sus clientes. A diferencia de la master key, un único secreto de operador estático, las virtual keys residen en la base de datos, cada una con su propio alcance de modelo, presupuesto y límites de RPM/TPM. Emita uno por aplicación, tenant o entorno, y revocarlo o cambiar su alcance sin tocar nada más.

Toda la administración de claves se realiza en la API de administración y requiere la master key:

Authorization: Bearer $MASTER_KEY

Crear una clave

curl -X POST $BASE/admin/keys \
  -H "Authorization: Bearer $MASTER_KEY" -H "content-type: application/json" -d '{
    "name": "frontend-prod",
    "allowedModels": ["general", "image-default"],
    "maxBudgetCents": 50000,
    "budgetReset": "monthly",
    "rpm": 600,
    "tpm": 200000
  }'

La respuesta incluye la clave en texto plano:

{
  "data": {
    "id": "…",
    "name": "frontend-prod",
    "keyPrefix": "sk-abcdefg",
    "key": "sk-…",
    "allowedModels": ["general", "image-default"],
    "maxBudgetCents": 50000,
    "budgetReset": "monthly",
    "rpm": 600,
    "tpm": 200000,
    "spendCents": "0",
    "enabled": true,
    "private": false,
    "copyable": true
  }
}

Campos

null siempre significa "sin límite". Los límites y el presupuesto se aplican en Redis y se reflejan en Postgres para una contabilidad duradera.

Visores

allowedModels se compara con el nombre del public model de la solicitud. Una clave que llama a un modelo fuera de su alcance obtiene 403 con el código model_not_allowed. Una matriz vacía es un "todos los modelos" explícito; úsela solo para herramientas de operadores confiables, no para claves orientadas al cliente.

Presupuestos y límites

• Presupuesto: antes de ejecutar la solicitud upstream, AI Gateway reserva de forma atómica una estimación conservadora del costo máximo, usando los precios del Catálogo de modelos o los precios específicos del deployment. Al finalizar, sustituye la reserva por el uso exacto informado por el proveedor. Una key con presupuesto limitado no puede usar deployments de precio desconocido, porque no sería posible garantizar el límite.
• RPM/TPM: La admisión de RPM y las reservas de TPM conservadoras son atómicas en Redis en todas las réplicas. Los tokens exactos se concilian en el momento de la liquidación; exceder cualquiera de los dos devuelve 429 con el código rate_limit_exceeded. Las unidades de búsqueda de reranking contribuyen al gasto y los presupuestos, pero nunca sintetizan tokens para TPM; RPM todavía cuenta cada solicitud de cambio de clasificación.
• headers: cuando una clave tiene algún límite, las respuestas incluyen los headers x-ratelimit-limit-* / x-ratelimit-remaining-* / x-ratelimit-reset-* coincidentes (solicitudes, tokens y centavos de presupuesto), para que los clientes puedan retroceder antes de ser limitados.

Administrar claves

# List (filter + paginate)
GET /admin/keys?limit=50&offset=0&enabled=true&publicModel=general&q=frontend

# Update scope, limits, or budget (same fields; send null to clear a limit)
PATCH /admin/keys/:id   { "rpm": 1200, "allowedModels": ["general"] }

# Re-enable or disable without deleting
PATCH /admin/keys/:id   { "enabled": false }

# Reset accumulated spend now (e.g. after a billing dispute)
PATCH /admin/keys/:id   { "resetSpend": true }

# Permanently delete
DELETE /admin/keys/:id

Las lecturas nunca devuelven el hash ni el texto plano de la clave; solo keyPrefix, que basta para identificarla en registros y paneles, además de private y copyable.

Volver a copiar una clave

GET /admin/keys/:id/secret      →  { "data": { "key": "sk-…" } }

Es la única ruta que devuelve una clave después de crearla. Requiere keys:write (una clave copiada vale tanto como una escrita), responde con Cache-Control: no-store y cada llamada queda en el registro de auditoría, incluidas las rechazadas. El campo copyable de la clave indica si funcionará:

El valor descifrado se verifica contra el hash con el que la clave se autentica, así que lo que copias es siempre la clave que funciona hoy. El dashboard la copia directamente al portapapeles y nunca la muestra en la página.

Claves privadas

Una clave creada con "private": true solo guarda su hash: el texto plano está en la respuesta de creación y en ningún otro lugar. Úsala para credenciales que nunca deban poder recuperarse del gateway, como una clave de despliegue de larga duración.

# Erase a key's stored secret. One way: the plaintext no longer exists anywhere.
PATCH /admin/keys/:id   { "private": true }

{"private": false} se rechaza: solo rotarla puede volver copiable una clave privada, porque solo un secreto nuevo puede almacenarse. Las claves emitidas antes de que se pudieran copiar son privadas.

Para impedir las copias en todo el gateway a la vez, define VIRTUAL_KEY_SECRET_ACCESS=sealed y reinicia: ninguna credencial puede copiar una clave, ni siquiera la master key. Los secretos almacenados siguen cifrados en reposo, así que reabrir el acceso no requiere claves nuevas. Sellar es una política de acceso; una clave que nunca debe almacenarse se crea privada.

Rotación y fugas

Las virtual keys son independientes de MASTER_KEY, por lo que rotar la master key no las invalida.

# New secret, same key: id, scope, limits, spend and logs stay.
POST /admin/keys/:id/rotate                         # keeps the key as private as it was
POST /admin/keys/:id/rotate   { "private": false }  # and stores the new secret for copying

La respuesta trae la nueva clave en texto plano, igual que una creación. El secreto anterior deja de autenticar de inmediato, en todas las réplicas, y los client secrets de realtime emitidos con él dejan de funcionar también; así que actualiza los clientes justo después de rotar, o emite una segunda clave y migra primero si importa el tiempo sin servicio.

Si se filtra una clave, rótala (o usa PATCH … {"enabled": false} para cortar el acceso mientras investigas) y audita gateway_operations y los registros estructurados de acceso de administrador. Para fugas de master key y credenciales de proveedor, consulta Operación del gateway.