Saltar para o conteúdo principal
Toda credencial de longa duração deveria ser substituída em um cronograma, e imediatamente a qualquer indício de exposição. A maneira segura de rotacionar credenciais de chave de api nunca é mutar uma chave ao vivo no lugar — é cunhar uma nova, mover o tráfego para ela, e aposentar a antiga uma vez que nada depende dela. Feito nessa ordem, nunca há um momento sem uma chave funcional. Esta página é o playbook passo a passo. Para o ciclo de vida mais amplo da chave (criar / desabilitar / deletar) veja Gerenciar chaves; para cada campo que uma chave carrega veja O objeto token.
Todas as ações de console aqui vivem na tela Keys (/console/token) e rodam no seu token de sessão / acesso — não na chave de relay. Criar, editar, desabilitar ou deletar uma chave exige o papel de Developer ou superior. Apenas chamadas de inferência /v1/* usam a chave de relay sk-orca-….

​
1. Por que rotacionar, e por que nunca no lugar

Uma chave no OrcaRouter é uma identidade imutável, não apenas uma string — ela carrega sua própria lista de permissão de modelo, lista de permissão de IP, limite de gasto, expiração e anexos de política. Você não pode mudar o material secreto de uma chave existente; a credencial e as restrições são emitidas juntas na criação. Então “rotacionar” significa emitir uma sucessora e migrar para ela. Faça-o:
  • em uma cadência fixa para qualquer credencial de produção (trimestral é uma baseline comum);
  • no momento em que uma chave é suspeita de vazada — embora para um vazamento confirmado, corte-a primeiro e rotacione em segundo (veja Resposta a chave vazada);
  • sempre que o dono da chave (um funcionário, uma integração de fornecedor, um agente desativado) muda.
O plaintext (sk-orca-…) é mostrado uma vez, na criação — copie-o então. Depois o console mostra apenas uma forma mascarada como orca-7Bf****wxyz. Um Developer+ pode re-revelar o plaintext de uma chave comum depois, mas uma chave com escopo de gateway (is_firewall_gateway) exige Admin para ler seu plaintext novamente — então trate a primeira revelação da chave de gateway como sua única cópia confiável.

​
2. A sequência de rotação de chave de api

Todo o ponto é uma sobreposição limpa: a nova chave funciona antes da antiga parar. Quatro passos.
1

Crie a chave sucessora

Cunhe uma nova chave com o mesmo escopo que a que você está substituindo — os mesmos model_limits, allow_ips, credit_limit_usd, expired_time, e os mesmos guardrail_id / firewall_policy_id. Copie o plaintext imediatamente. A rotação é o momento ideal para apertar o escopo também: descarte um modelo que o agente não usa mais, ou estreite a lista de permissão de IP.
2

Migre o tráfego

Faça deploy da nova sk-orca-… para cada chamador — config, gerenciador de segredos, variável de CI, runtime do agente. Faça o rollout da mesma forma que você entrega qualquer mudança de segredo. Ambas as chaves estão ao vivo neste ponto, então os deployments podem ser escalonados sem uma interrupção.
3

Verifique que a nova chave está carregando carga

Confirme que a sucessora está de fato servindo tráfego antes de tocar a antiga. Observe o used_quota da nova chave subir enquanto o da antiga se achata — o uso por chave é seu sinal de cutover.
4

Aposente a chave antiga

Uma vez que a chave antiga não mostra tráfego, desabilite-a primeiro (reversível) e observe os retardatários, depois delete-a de vez. Desabilitar é a pausa; deletar é o ponto sem retorno.
Defina um rótulo environment em cada chave — reutilize-o entre a chave antiga e a nova, ou incremente-o (prod → prod-2026q2) — para que a sucessora e a predecessora sejam rotuladas de forma distinta enquanto ambas estão ao vivo durante a janela de sobreposição.

​
3. Uma rotação concreta, via REST

Tudo abaixo é uma ação de console — estas rotas de gerenciamento rodam sob sua sessão (UserAuth), não na chave de relay. Suponha que você está substituindo a chave de um agente sumarizador agendado. Crie a sucessora com o mesmo escopo: 
# Token de sessão de console — NÃO uma chave 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
  }'
A resposta retorna o plaintext uma vez ("data": "sk-orca-…"). Copie-o, faça deploy para o sumarizador, e confirme que a nova chave está servindo antes de prosseguir. Quando a chave antiga (id 481) não mostra tráfego, desabilite e depois delete: 
# Pause primeiro (reversível) — defina o status da chave antiga para 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}'

# Uma vez que você tem certeza de que nada depende dela — revogue de vez
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
O status de uma chave é um de Enabled (1), Disabled (2), Expired (3) ou Exhausted (4). Desabilitar a define como Disabled; toda requisição que a chave faz é então rejeitada enquanto sua config, anexos e histórico permanecem intactos. Deletar é permanente — a credencial nunca pode autorizar uma requisição novamente, e uma chave deletada não é recuperável.
Você pode fazer tudo isso sem a API — a tela Keys tem New key, um toggle Disabled por chave e Delete (única ou em lote). A forma REST acima é para scriptar rotações agendadas.

​
4. Rotacionando chaves vinculadas a política e de gateway

Os anexos de guardrail e firewall de uma chave vivem na chave, então a sucessora deve carregar os mesmos guardrail_id e firewall_policy_id para aplicar a mesma postura. Duas coisas para saber:
Guardrails e políticas de firewall são recursos nomeados com escopo de workspace, compartilhados pelas chaves. Rotacionar uma chave não toca a própria política; você está apenas re-apontando uma chave nova para os guardrail_id / firewall_policy_id existentes. A política continua governando o tráfego sem interrupção.
Uma chave com is_firewall_gateway definido conduz as rotas do gateway do Firewall (/api/v1/firewall/*). Cunhar uma, e re-revelar seu plaintext, ambos exigem Admin. Como você não pode reler seu segredo casualmente, capture o plaintext da nova chave de gateway na criação e armazene-o no seu gerenciador de segredos antes de fazer o cutover.
Não reutilize uma única chave — de gateway ou não — em muitos agentes e “rotacione” editando limites. Uma chave por agente mantém cada rotação isolada e o raio de explosão pequeno. Veja a Checklist de menor agência.

​
5. Rotação de emergência (vazamento suspeito)

Se você acha que uma chave está exposta, a ordem inverte: estanque o sangramento primeiro, migre em segundo.
  1. Desabilite a chave suspeita imediatamente para que ela não possa autorizar nada enquanto você investiga — ou delete-a de imediato se o vazamento for confirmado.
  2. Cunhe a sucessora e faça o rollout como em §2.
  3. Revise o que a chave vazada fez antes de cortá-la: filtre os logs de requisição por aquela chave (token) para escopar o raio de explosão.
O runbook completo de incidente está em Resposta a chave vazada.
Um expired_time curto é seguro de rotação: uma chave expirável se aposenta sozinha mesmo se você esquecer a rotação manual, limitando por quanto tempo qualquer credencial única pode ser abusada.

​
6. Próximos passos

Gerenciar chaves

O ciclo de vida criar / desabilitar / revogar sobre o qual estes passos se constroem.

Vincular políticas a uma chave

Carregue o mesmo guardrail e a mesma política de firewall para a sucessora.

Chaves expiráveis

Defina uma expiração para que as chaves se rotacionem sozinhas em um prazo.

Resposta a chave vazada

O caminho de emergência quando uma credencial é exposta.
A rotação é apenas sobreposição disciplinada: uma sucessora que funciona antes da predecessora parar. Mantenha cada chave estreitamente escopada e a transição permanece entediante — que é exatamente o que você quer de uma rotação de credencial.