Saltar al contenido principal
Toda credencial de larga duración debería reemplazarse en un calendario, e inmediatamente ante cualquier indicio de exposición. La forma segura de rotar claves API nunca es mutar una clave en vivo en su lugar — es acuñar una nueva, mover el tráfico a ella, y retirar la vieja una vez que nada dependa de ella. Hecho en ese orden nunca hay un momento sin una clave funcional. Esta página es el manual paso a paso. Para el ciclo de vida más amplio de las claves (crear / deshabilitar / eliminar) ver Gestionar claves; para cada campo que lleva una clave ver El objeto token.
Todas las acciones de consola aquí viven en la pantalla Keys (/console/token) y se ejecutan sobre tu token de sesión / acceso — no la clave de relay. Crear, editar, deshabilitar o eliminar una clave requiere el rol Developer o superior. Solo las llamadas de inferencia /v1/* usan la clave de relay sk-orca-….

​
1. Por qué rotar, y por qué nunca en su lugar

Una clave en OrcaRouter es una identidad inmutable, no solo una cadena — lleva su propia lista de permitidos de modelo, lista de permitidos de IP, tope de gasto, expiración y adjuntos de política. No puedes cambiar el material secreto de una clave existente; la credencial y las restricciones se emiten juntas en la creación. Así que “rotar” significa emitir un sucesor y migrar a él. Hazlo:
  • en una cadencia fija para cualquier credencial de producción (trimestral es una línea base común);
  • en el momento en que se sospecha que una clave está filtrada — aunque para una filtración confirmada, córtala primero y rota después (ver Respuesta a clave filtrada);
  • siempre que cambie el dueño de la clave (un empleado, una integración de proveedor, un agente dado de baja).
El texto plano (sk-orca-…) se muestra una vez, en la creación — cópialo entonces. Después la consola muestra solo una forma enmascarada como orca-7Bf****wxyz. Un Developer+ puede volver a revelar el texto plano de una clave ordinaria más tarde, pero una clave con alcance de gateway (is_firewall_gateway) requiere Admin para leer su texto plano de nuevo — así que trata la primera revelación de la clave de gateway como tu única copia confiable.

​
2. La secuencia de rotación de clave API

Todo el punto es un solapamiento limpio: la clave nueva funciona antes de que la vieja se detenga. Cuatro pasos.
1

Crea la clave sucesora

Acuña una clave nueva con el mismo alcance que la que reemplazas — los mismos model_limits, allow_ips, credit_limit_usd, expired_time, y los mismos guardrail_id / firewall_policy_id. Copia el texto plano de inmediato. La rotación es el momento ideal para endurecer el alcance también: suelta un modelo que el agente ya no usa, o estrecha la lista de permitidos de IP.
2

Migra el tráfico

Despliega la nueva sk-orca-… a cada llamante — configuración, gestor de secretos, variable de CI, runtime del agente. Lánzala de la misma forma que envías cualquier cambio de secreto. Ambas claves están en vivo en este punto, así que los despliegues pueden escalonarse sin un corte.
3

Verifica que la clave nueva lleva carga

Confirma que el sucesor realmente está sirviendo tráfico antes de tocar la vieja. Observa subir el used_quota de la clave nueva mientras el de la clave vieja se aplana — el uso por clave es tu señal de transición.
4

Retira la clave vieja

Una vez que la clave vieja no muestra tráfico, deshabilítala primero (reversible) y vigila rezagados, luego elimínala de forma definitiva. Deshabilitar es la pausa; eliminar es el punto sin retorno.
Establece una etiqueta environment en cada clave — reúsala entre la clave vieja y la nueva, o súbela (prod → prod-2026q2) — para que el sucesor y el predecesor estén etiquetados de forma distinta mientras ambos están en vivo durante la ventana de solapamiento.

​
3. Una rotación concreta, vía REST

Todo lo de abajo es una acción de consola — estas rutas de gestión se ejecutan bajo tu sesión (UserAuth), no la clave de relay. Supón que reemplazas la clave de un agente de resumen programado. Crea el sucesor con el mismo alcance: 
# Token de sesión de consola — NO una clave de relay sk-orca-…
curl https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer-2026q2",
    "environment": "prod",
    "model_limits_enabled": true,
    "model_limits": "openai/gpt-4o-mini",
    "credit_limit_usd": 50,
    "expired_time": -1,
    "guardrail_id": 12,
    "firewall_policy_id": 7
  }'
La respuesta devuelve el texto plano una vez ("data": "sk-orca-…"). Cópialo, despliégalo al agente de resumen, y confirma que la clave nueva está sirviendo antes de continuar. Cuando la clave vieja (id 481) no muestra tráfico, deshabilita y luego elimina: 
# Pausa primero (reversible) — establece el estado de la clave vieja a Disabled (2)
curl -X PUT https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 481, "status": 2}'

# Una vez que estés seguro de que nada depende de ella — revoca de forma definitiva
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
El estado de una clave es uno de Enabled (1), Disabled (2), Expired (3) o Exhausted (4). Deshabilitar lo establece a Disabled; cada solicitud que hace la clave es entonces rechazada mientras su configuración, adjuntos e historial quedan intactos. Eliminar es permanente — la credencial nunca puede volver a autorizar una solicitud, y una clave eliminada no es recuperable.
Puedes hacer todo esto sin la API — la pantalla Keys tiene New key, un conmutador Disabled por clave, y Delete (individual o por lote). La forma REST de arriba es para programar rotaciones automatizadas.

​
4. Rotar claves vinculadas a política y de gateway

Los adjuntos de guardrail y firewall de una clave viven en la clave, así que el sucesor debe llevar los mismos guardrail_id y firewall_policy_id para aplicar la misma postura. Dos cosas que saber:
Los guardrails y las políticas de firewall son recursos nombrados con alcance de espacio de trabajo, compartidos entre claves. Rotar una clave no toca la política en sí; solo estás reapuntando una clave nueva al guardrail_id / firewall_policy_id existente. La política sigue gobernando el tráfico sin interrupción.
Una clave con is_firewall_gateway establecido impulsa las rutas del gateway del Firewall (/api/v1/firewall/*). Acuñar una, y volver a revelar su texto plano, ambas requieren Admin. Como no puedes releer casualmente su secreto, captura el texto plano de la nueva clave de gateway en la creación y guárdalo en tu gestor de secretos antes de hacer la transición.
No reúses una sola clave — de gateway o no — entre muchos agentes y “rotes” editando límites. Una clave por agente mantiene cada rotación aislada y el radio de explosión pequeño. Ver el Checklist de mínima agencia.

​
5. Rotación de emergencia (filtración sospechada)

Si crees que una clave está expuesta, el orden se invierte: detén el sangrado primero, migra después.
  1. Deshabilita la clave sospechosa de inmediato para que no pueda autorizar nada mientras investigas — o elimínala directamente si la filtración está confirmada.
  2. Acuña el sucesor y lánzalo como en §2.
  3. Revisa qué hizo la clave filtrada antes de cortarla: filtra los logs de solicitudes por esa clave (token) para acotar el radio de explosión.
El runbook de incidente completo está en Respuesta a clave filtrada.
Un expired_time corto es el seguro de rotación: una clave expirante se retira a sí misma incluso si olvidas la rotación manual, limitando cuánto tiempo puede abusarse de cualquier credencial.

​
6. Próximos pasos

Gestionar claves

El ciclo de vida crear / deshabilitar / revocar sobre el que se construyen estos pasos.

Vincular políticas a una clave

Lleva el mismo guardrail y política de firewall al sucesor.

Claves expirantes

Establece una expiración para que las claves se roten a sí mismas en un plazo.

Respuesta a clave filtrada

La ruta de emergencia cuando una credencial se expone.
La rotación es solo solapamiento disciplinado: un sucesor que funciona antes de que el predecesor se detenga. Mantén cada clave estrechamente acotada y el traspaso se mantiene aburrido — que es exactamente lo que quieres de una rotación de credencial.