> For the complete documentation index, see [llms.txt](https://docs.skail.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skail.dev/operar/chaves-criar-rotacionar-revogar.md).

# Chaves: criar, rotacionar, revogar

O ciclo de vida da chave de um environment: onde ela é usada, como criar, como trocar sem parar a aplicação e como revogar.

## Quando você precisa disto

Ao criar um environment (primeira chave), ao suspeitar de vazamento, em rotação periódica por política de segurança, ao desligar um sistema que tinha a chave.

## Onde a chave é usada

Em dois lugares, com o mesmo valor: `SKAIL_KEY` no runtime da aplicação (header `skail-key` em toda chamada ao skail) e o header `skail-key` de quem dispara trigger e fire. Sempre acompanhada do namespace do environment; a chave só autoriza o environment a que pertence.

Desabilitar ou excluir uma chave leva até um minuto para valer em todas as chamadas.

## Criar

1. No portal, abra o environment e gere uma chave.
2. Copie no ato para o cofre de segredos do host (Kubernetes Secret, Key Vault, variáveis do serviço de container). Não a coloque em arquivos versionados, em URL nem em log.
3. Configure `SKAIL_KEY` na aplicação e o header em quem dispara. Confirme com uma execução de teste no Monitor.

## Rotacionar

O procedimento depende de o environment aceitar duas chaves ativas ao mesmo tempo.

Com duas chaves ativas, a rotação não para nada:

1. Gere a chave nova; a antiga continua válida.
2. Atualize `SKAIL_KEY` na aplicação e faça o rolling restart; atualize o header em quem dispara. Execuções em andamento não são afetadas: a chave autentica chamadas, não execuções.
3. Confirme no Monitor que execuções novas chegam e que o runtime as recebe (sem `Unauthenticated` no log).
4. Desabilite a chave antiga. Aguarde um minuto e confira que nada quebrou; então exclua.

Com uma chave ativa por vez, a rotação tem uma janela de indisponibilidade de até um minuto entre trocar a chave no portal e propagar a nova para todos os processos; faça em janela de baixo tráfego. Execuções aceitas antes da troca não se perdem; o que falha nesse intervalo é o trigger (retry do chamador) e a busca de trabalho (o runtime volta a receber trabalho quando a chave nova propaga).

## Revogar

Desabilite a chave no portal. Em até um minuto, toda chamada com ela recebe 401/403 e o runtime que a usa para de receber trabalho com `Unauthenticated`. Execuções em andamento esperam até um runtime com chave válida voltar; nada se perde.

## O que observar no Monitor e nos logs

Após qualquer mudança: execuções novas aparecendo no Monitor; ausência de `Unauthenticated`/`PermissionDenied` no log do runtime; ausência de 401/403 no sistema que dispara.

## Se der errado

Trocou a chave e a aplicação parou de receber trabalho: `SKAIL_KEY` com a chave antiga em algum processo, ou chave do environment errado. Trigger retorna 401 depois da rotação: quem dispara ainda usa a antiga. Ver [Troubleshooting](/operar/troubleshooting.md).

## Próximos passos

[Segurança](/aprender/garantias/seguranca.md), [Autenticação e headers](/construir/api-http/autenticacao-e-headers.md), [Environments](/construir/portal/environments.md).