Saltar al contenido principal
Una credencial de larga duración es una responsabilidad que crece silenciosamente: el agente se da de baja, la demo termina, el contratista se va — pero la clave sigue funcionando hasta que alguien recuerda revocarla. Una clave api que expira invierte ese valor por defecto. Estableces una fecha de fin cuando acuñas la clave, y OrcaRouter deja de autorizarla en el momento en que esa fecha pasa — sin tarea de limpieza que olvidar, sin ventana de filtrada-pero-aún-viva. La expiración es un campo del objeto token: expired_time. Esta página es la guía enfocada a ese único control. Para el lado del tope de gasto de la misma pantalla, ver Cuota, tope y expiración.

​
1. Por qué establecer una clave api que expira

El punto de una clave con límite de tiempo es hacer que el resultado seguro sea el por defecto. Algunos casos donde vale la pena:

Agentes efímeros

Un trabajo programado o agente de vida corta obtiene una clave que muere con el ciclo de vida del despliegue. Una tarea cron olvidada no puede seguir gastando meses después.

Demos y pruebas

Entrega a un prospecto una clave que funciona durante la evaluación y luego se apaga por sí sola — sin revocación de seguimiento necesaria.

Contratistas y proveedores

Da alcance a una credencial a la ventana del compromiso. Cuando el contrato termina, también la clave.

Acceso con alcance de incidente

Concede una clave estrecha y de vida corta durante un incidente para que el acceso elevado no pueda sobrevivir al incidente mismo.
La expiración se combina naturalmente con el resto de una clave de mínima agencia — una lista de modelos permitidos, una lista de IPs permitidas y un tope de gasto. Cada uno acota un eje diferente; juntos mantienen pequeño el radio de explosión de una clave comprometida. Ver la Lista de verificación de mínima agencia.

​
2. El campo expired_time

La expiración de una clave vive en un único campo del objeto token:
CampoTipoSignificado
expired_timeMarca de tiempo Unix (segundos)El instante absoluto en que la clave deja de autorizar. -1 significa nunca expira.
Dos cosas a tener en cuenta:
  • expired_time es absoluto, no una duración. Estableces el momento en que la clave muere, no “30 días a partir de ahora” — el selector de fecha de la consola calcula la marca de tiempo por ti.
  • El valor por defecto para una clave nueva es -1 (nunca). Una clave solo expira si le das una marca de tiempo real; dejar el campo intacto acuña una clave que no expira.
Una clave que no expira (expired_time = -1) es la elección correcta solo para una credencial que rotas activamente. Si puedes nombrar la fecha en que una clave debería dejar de funcionar — y para agentes, demos y contratistas usualmente puedes — establécela. Una clave -1 sin atención es la que más probablemente sobreviva a su propósito.

​
3. Establecer una expiración en la consola

Establecer una expiración es una acción de consola sobre tu token de sesión / acceso — no algo que pasas en una llamada de relay. Crear o editar una clave requiere el rol Developer o superior.
  1. Abre Keys (/console/token) y crea una nueva clave, o edita una existente.
  2. En el campo expiry, elige la fecha y hora en que la clave debería dejar de funcionar. Déjalo en blanco (o establece never) para mantener la clave permanente.
  3. Guarda. El cambio surte efecto inmediatamente — sin redespliegue, sin cambio de código del agente.
Editar la expiración en una clave existente es en vivo: extiende una clave que está a punto de caducar, o adelanta su expiración para retirarla antes, y el nuevo plazo aplica en la siguiente solicitud.
Solo las llamadas de relay /v1/* llevan la clave sk-orca-…. La expiración que estableces aquí gobierna esa clave de relay, pero la configuras desde la sesión de consola, nunca enviando la clave de relay a una ruta de gestión.

​
4. Qué hace una clave expirada

Cuando una clave se presenta después de que su expired_time ha pasado, el gateway la rechaza en la capa de autenticación — la solicitud nunca llega a un modelo, así que no cuesta cuota. El estado de la clave pasa a Expired, uno de los estados finales automáticos que una clave puede alcanzar:
EstadoCómo se alcanza
EnabledActiva; las solicitudes están autorizadas.
DisabledLa pausaste; reversible.
ExpiredPasado su expired_time — se alcanza automáticamente.
ExhaustedPor encima de su cuota / tope de gasto — se alcanza automáticamente.
Expired es terminal en el sentido de que la clave no autorizará de nuevo por sí sola. Si la necesitas de vuelta, edita la clave para empujar expired_time al futuro (Developer+) y vuelve a Enabled en la siguiente solicitud — la clave, sus límites y sus adjuntos de política se conservan todos. Para retirar una clave para siempre en su lugar, revócala.
Expiración vs. deshabilitar vs. revocar. La expiración es el interruptor de apagado programado — decides el plazo de antemano y te alejas. Deshabilitar es la pausa manual, reversible para un incidente. Revocar (eliminar) es permanente. Recurre a la expiración cuando ya sabes cuándo una credencial debería dejar de importar.

​
5. Un ejemplo trabajado: una clave de demo de dos semanas

Supón que le das a un prospecto una clave para una evaluación de 14 días. Quieres que llame a un modelo barato, gaste no más que un presupuesto fijo, y se apague cuando termine la prueba — todo sin un recordatorio de calendario para revocarla. En el diálogo New key, establece:
  • model_limits: ["openai/gpt-4o-mini"] — la demo no puede recurrir a un modelo más caro.
  • credit_limit_usd: un presupuesto de prueba fijo — un bucle descontrolado no puede excederlo.
  • expired_time: el fin de la ventana de 14 días — la clave deja de autorizar por sí sola cuando la prueba termina.
Después del plazo, cualquier solicitud adicional con esta clave se rechaza sin cuota gastada, y la clave muestra Expired en la lista. Nada que limpiar de tu parte; la credencial se retiró sola. 
# Before expiry — authorized
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role":"user","content":"ping"}]}'

# After expiry — the same call is rejected at the auth layer,
# the model is never invoked, and no quota is consumed.

​
6. Quién puede hacer qué

La expiración está gobernada por la misma puerta de rol que el resto del ciclo de vida de una clave, con alcance de tu espacio de trabajo activo:
AcciónRol mínimo
Ver la expiración de una claveViewer
Establecer o cambiar expired_time (crear / editar una clave)Developer
Volver a revelar el texto plano de una clave ordinariaDeveloper
Leer el texto plano de una clave con alcance de gateway (is_firewall_gateway)Admin
Para el ciclo de vida completo — crear, deshabilitar, revocar — y el patrón de rotación que se combina con la expiración, ver Gestionar claves.

​
7. Próximos pasos

Cuota, tope y expiración

El hermano de tope de gasto de la expiración — acota una clave por dólares además de por tiempo.

Rotación de claves

El traspaso sin tiempo de inactividad que evita que una clave sin expiración viva para siempre.

El objeto token

Cada campo que lleva una clave, incluyendo expired_time, y qué restringe cada uno.

Lista de verificación de mínima agencia

Combina la expiración con límites de modelo, listas de IPs permitidas y topes de gasto para una clave de radio de explosión mínimo.
Una clave que sabe cuándo detenerse es una credencial menos que tienes que recordar retirar. Establece expired_time siempre que puedas nombrar la fecha — y deja que el gateway haga la limpieza por ti.