Saltar para o conteúdo principal
Uma credencial de longa duração é um passivo que cresce silenciosamente: o agente é desativado, a demo termina, o contratado segue em frente — mas a chave continua funcionando até que alguém se lembre de revogá-la. Uma chave de api que expira inverte esse padrão. Você define uma data de término quando cunha a chave, e o OrcaRouter para de autorizá-la no momento em que essa data passa — sem tarefa de limpeza para esquecer, sem janela vazada-mas-ainda-viva. A expiração é um campo no objeto token: expired_time. Esta página é o guia focado nesse único controle. Para o lado de limite de gasto da mesma tela, veja Cota, limite e expiração.

​
1. Por que configurar uma chave de api que expira

O ponto de uma chave com prazo é tornar o resultado seguro o resultado padrão. Alguns casos em que isso compensa:

Agentes efêmeros

Um job agendado ou agente de vida curta recebe uma chave que morre com o ciclo de vida do deployment. Uma tarefa cron esquecida não pode continuar gastando meses depois.

Demos e trials

Entregue a um prospect uma chave que funciona pela duração da avaliação e depois apaga por conta própria — sem revogação de acompanhamento necessária.

Contratados e fornecedores

Dê escopo a uma credencial para a janela do contrato. Quando o contrato termina, a chave também.

Acesso com escopo de incidente

Conceda uma chave estreita e de vida curta durante um incidente para que o acesso elevado não possa sobreviver ao próprio incidente.
A expiração combina naturalmente com o resto de uma chave de menor agência — uma allow-list de modelo, uma allow-list de IP e um limite de gasto. Cada uma delimita um eixo diferente; juntas elas mantêm pequeno o raio de explosão de uma chave comprometida. Veja o Checklist de menor agência.

​
2. O campo expired_time

A expiração de uma chave vive em um único campo no objeto token:
CampoTipoSignificado
expired_timetimestamp Unix (segundos)O instante absoluto em que a chave para de autorizar. -1 significa nunca expira.
Duas coisas a ter em mente:
  • expired_time é absoluto, não uma duração. Você define o momento em que a chave morre, não “30 dias a partir de agora” — o seletor de data do console computa o timestamp para você.
  • O padrão para uma nova chave é -1 (nunca). Uma chave só expira se você lhe der um timestamp real; deixar o campo intocado cunha uma chave que não expira.
Uma chave que não expira (expired_time = -1) é a escolha certa apenas para uma credencial que você rotaciona ativamente. Se você consegue nomear a data em que uma chave deveria parar de funcionar — e para agentes, demos e contratados você geralmente consegue — defina-a. Uma chave -1 sem supervisão é a que tem mais chance de sobreviver ao seu propósito.

​
3. Definir uma expiração no console

Definir uma expiração é uma ação de console no seu token de sessão / acesso — não algo que você passa em uma chamada de relay. Criar ou editar uma chave exige o papel de Developer ou superior.
  1. Abra Keys (/console/token) e crie uma nova chave, ou edite uma existente.
  2. No campo de expiração, escolha a data e a hora em que a chave deve parar de funcionar. Deixe em branco (ou defina como nunca) para manter a chave permanente.
  3. Salve. A mudança entra em vigor imediatamente — sem redeploy, sem mudança no código do agente.
Editar a expiração em uma chave existente é ao vivo: estenda uma chave que está prestes a vencer, ou puxe a sua expiração para frente para aposentá-la mais cedo, e o novo prazo se aplica na próxima requisição.
Apenas as chamadas de relay /v1/* carregam a chave sk-orca-…. A expiração que você define aqui governa aquela chave de relay, mas você a configura a partir da sessão do console, nunca enviando a chave de relay para uma rota de gerenciamento.

​
4. O que uma chave expirada faz

Quando uma chave é apresentada depois que o seu expired_time passou, o gateway a rejeita na camada de auth — a requisição nunca chega a um modelo, então não custa nenhuma cota. O status da chave move para Expired, um dos estados-finais automáticos que uma chave pode atingir:
StatusAtingido como
EnabledAtiva; as requisições são autorizadas.
DisabledVocê a pausou; reversível.
ExpiredPassou do seu expired_time — atingido automaticamente.
ExhaustedUltrapassou sua cota / limite de gasto — atingido automaticamente.
Expired é terminal no sentido de que a chave não autorizará de novo por conta própria. Se você precisa dela de volta, edite a chave para empurrar expired_time para o futuro (Developer+) e ela retorna a Enabled na próxima requisição — a chave, seus limites e seus anexos de política são todos preservados. Para aposentar uma chave de vez em vez disso, revogue-a.
Expiração vs. desabilitar vs. revogar. A expiração é o interruptor de desligar agendado — você decide o prazo antecipadamente e segue em frente. Desabilitar é a pausa manual e reversível para um incidente. Revogar (deletar) é permanente. Recorra à expiração sempre que você já souber quando uma credencial deve parar de importar.

​
5. Um exemplo trabalhado: uma chave de demo de duas semanas

Suponha que você esteja dando a um prospect uma chave para uma avaliação de 14 dias. Você quer que ela chame um modelo barato, gaste não mais que um orçamento fixo e apague quando o trial terminar — tudo sem um lembrete de calendário para revogá-la. No diálogo New key, defina:
  • model_limits: ["openai/gpt-4o-mini"] — a demo não pode buscar um modelo mais caro.
  • credit_limit_usd: um orçamento de trial fixo — um loop descontrolado não pode ultrapassá-lo.
  • expired_time: o fim da janela de 14 dias — a chave para de autorizar por conta própria quando o trial acaba.
Depois do prazo, qualquer requisição adicional nesta chave é rejeitada sem cota gasta, e a chave mostra Expired na lista. Nada para você limpar; a credencial se aposentou sozinha. 
# Antes da expiração — autorizada
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"}]}'

# Depois da expiração — a mesma chamada é rejeitada na camada de auth,
# o modelo nunca é invocado, e nenhuma cota é consumida.

​
6. Quem pode fazer o quê

A expiração é governada pelo mesmo portão de papel que o resto do ciclo de vida de uma chave, com escopo do seu workspace ativo:
AçãoPapel mínimo
Ver a expiração de uma chaveViewer
Definir ou mudar expired_time (criar / editar uma chave)Developer
Re-revelar o texto plano de uma chave comumDeveloper
Ler o texto plano de uma chave com escopo de gateway (is_firewall_gateway)Admin
Para o ciclo de vida completo — criar, desabilitar, revogar — e o padrão de rotação que combina com a expiração, veja Gerenciar chaves.

​
7. Próximos passos

Cota, limite e expiração

O irmão de limite de gasto da expiração — delimite uma chave por dólares assim como por tempo.

Rotação de chave

A transição sem downtime que impede uma chave que não expira de viver para sempre.

O objeto token

Cada campo que uma chave carrega, incluindo expired_time, e o que cada um restringe.

Checklist de menor agência

Combine a expiração com limites de modelo, allow-lists de IP e limites de gasto para uma chave de raio de explosão mínimo.
Uma chave que sabe quando parar é uma credencial a menos que você precisa lembrar de aposentar. Defina expired_time sempre que puder nomear a data — e deixe o gateway fazer a limpeza por você.