Certificação Claude Developer Foundations · parte 19 de 20
Identidade, segredos e chaves da API
Quem a sua aplicação é quando fala com a API do Claude, onde ficam as chaves que provam isso e como limitar o estrago quando uma chave vaza.
Publicada em · 27 min de leitura
Esta nota responde a uma pergunta que parece administrativa e é de segurança: quem a sua aplicação é quando fala com a API do Claude, onde ficam as chaves que provam isso e como limitar o estrago quando uma chave vaza.
Pense na chave de API como um crachá de acesso que não tem foto. Quem o carrega entra como se fosse o dono, e o porteiro não pergunta quem está por trás. Se o crachá cair na rua, quem o achou entra no seu prédio com as mesmas permissões. Por isso a aula trata a chave como parte do desenho da aplicação, e não como um detalhe de configuração que se resolve no fim do projeto.
A aula começa pelo conceito mais simples, que é o que a API enxerga como identidade. Depois entram o workspace como fronteira entre ambientes e times, o escopo e o tipo de cada chave, o menor privilégio, os lugares onde os segredos devem ficar, a rotação, a resposta a vazamento e a lista do que nunca pode sair da aplicação. O mecanismo da requisição, com os cabeçalhos e o caminho do erro 401, já está na aula 1.3 Mecânica da API Claude, e aqui ele só aparece quando é necessário para entender a decisão.
Mapa da aula
| Seção | O que responde |
|---|---|
| 1. Quem a aplicação é para a API | Que identidade a chamada carrega e qual é a diferença entre os tipos de chave? |
| 2. Workspaces: a fronteira entre ambientes e times | Como separar ambientes e times, e o que um workspace limita? |
| 3. O que cada chave pode fazer | Em que workspaces uma chave funciona, quem ela age como e quando ela para? |
| 4. Menor privilégio | Como dar a cada chave e a cada pessoa só o que precisam? |
| 5. Onde guardar segredos | Por que o gerenciador de segredos e a variável de ambiente, e por que nunca o código? |
| 6. Rotação e vazamento | Com que frequência trocar, e o que fazer quando uma chave vaza? |
| 7. O que nunca entra em prompt, log ou resposta | Quais valores devem ficar fora do fluxo de texto da aplicação, e por quê? |
| 8. Erros comuns e boas práticas | Quais armadilhas aparecem em projetos reais? |
| 9. Exercícios | O que dá para fazer sozinho? |
| 10. Glossário | Quais termos desta aula valem guardar? |
| 11. Fontes | Onde cada fato foi confirmado e o que ficou sem verificação? |
Parte 1: identidade e escopo
1. Quem a aplicação é para a API
Quando a sua aplicação chama o modelo, o servidor não sabe o nome do seu produto, nem o do seu repositório, nem quem é o usuário final que digitou a pergunta. Ele sabe apenas o que a credencial diz. Essa credencial é a identidade da chamada, e tudo o que a API conta (gasto, limite de taxa, registro de uso) é contado em cima dela. Se você entende a identidade, entende de quem é cada request.
A documentação de autenticação, consultada em 18/10/2026, lista três caminhos. A chave de API é um segredo estático, enviado como bearer token, e serve para desenvolvimento local, scripts e servidores em que você controla onde o segredo fica. A Workload Identity Federation troca um token emitido pelo provedor de identidade que você já usa (AWS, Google Cloud, Azure, GitHub Actions e outros) por um token de curta duração. A documentação a recomenda para cargas de produção na nuvem, porque ela elimina a chave que vive por meses no cofre de alguém. O App Attest é para apps de iOS e macOS distribuídos a usuários finais, que chamam a API direto do aparelho, sem servidor no meio. Dentro desta aula o foco é a chave de API, porque é o caminho que a maioria das equipes usa primeiro e o que mais vaza.
A escolha entre esses caminhos é a primeira decisão de identidade. A chave estática é simples de começar, mas ela continua válida até alguém apagá-la ou até a expiração chegar. A federação troca isso por tokens que vencem em pouco tempo, ao custo de configurar o provedor. A própria página de autenticação avisa que a federação não garante segurança sozinha: a cadeia de confiança é tão forte quanto a configuração do provedor, e um segredo de longa duração um salto acima, como uma credencial de nuvem que pode emitir tokens, ainda pode comprometê-la. Ou seja, trocar o tipo de credencial desloca o risco, não o elimina.
Dentro das chaves de API existem três tipos, e a diferença entre eles é de quem é a identidade. A chave pessoal age como você, com as permissões do seu papel, e para de funcionar quando você sai da organização. A chave de conta de serviço pertence a uma identidade que a organização gerencia, e é a escolha para integrações compartilhadas e para CI. A chave de workspace é o modelo legado: ela pertence ao workspace onde foi criada, não a uma pessoa, e continua funcionando mesmo que quem a criou saia da organização. Ela só para quando expira, é desativada ou apagada, ou quando o workspace é arquivado. Uma chave de workspace sem dono é parecida com uma chave de porta que ninguém sabe quem fez, e que continua abrindo a porta depois que a pessoa que a fez já foi embora. Por isso a documentação pede que integrações novas usem chaves ligadas a identidade.
2. Workspaces: a fronteira entre ambientes e times
Um workspace é uma área de trabalho dentro da organização. A documentação de workspaces, consultada na mesma data, diz que ele serve para separar projetos, ambientes ou times, mantendo o faturamento e a administração centralizados. Cada organização tem um Default Workspace, que não pode ser renomeado, arquivado nem apagado, e você pode criar outros, com membros, contas de serviço, chaves e limites próprios.
O motivo de separar fica claro com um exemplo simples. Imagine que todos os testes da equipe, os de desenvolvimento e os de produção usam a mesma área. Um script de teste que entra em loop consome o limite de requisições por minuto, e a aplicação de clientes começa a receber 429 no horário de pico. Ninguém fez nada errado na produção, e mesmo assim ela sofre. Com um workspace de testes separado, o loop esgota o limite do workspace de testes, e a produção continua com a capacidade dela. A separação não evita o erro, mas impede que o erro atravesse a fronteira.
Os limites são o segundo motivo. A documentação diz que você pode definir limite de gasto mensal por workspace, com alertas em faixas de consumo, e limites de requisições, tokens de entrada e tokens de saída por minuto. Os limites de workspace não podem passar dos limites da organização, e o Default Workspace não recebe limites próprios. Os limites da organização valem sempre, mesmo que a soma dos workspaces seja maior. Isso significa que um workspace de testes com teto de gasto baixo limita o dano financeiro de uma chave vazada naquele ambiente, e a chave de produção segue sem esse teto.
Os papéis dentro de cada workspace controlam quem pode criar chaves e quem pode mudar configurações. A tabela abaixo resume os cinco papéis documentados.
| Papel | O que pode fazer |
|---|---|
| Workspace User | Usar o playground, sem criar chaves. |
| Workspace Limited Developer | Criar e gerenciar chaves e usar a API, sem acesso a visualização de rastreamento de sessões nem download de arquivos. |
| Workspace Developer | Criar e gerenciar chaves e usar a API. |
| Workspace Admin | Controle total das configurações e dos membros do workspace. |
| Workspace Billing | Ver informações de faturamento, herdado do papel de faturamento da organização. |
Dois detalhes de herança importam. Administradores da organização recebem automaticamente o papel de Workspace Admin em todos os workspaces, e quem tem o papel de faturamento recebe o de Workspace Billing, que não pode ser atribuído manualmente. Usuários e desenvolvedores da organização precisam ser adicionados a cada workspace. Por isso, uma pessoa que deveria acessar só o workspace de testes não deve ser promovida a administradora da organização: a promoção abre todos os workspaces de uma vez.
O arquivamento é a operação mais destrutiva do console, e vale conhecê-la antes de precisar. A documentação diz que arquivar um workspace o desativa, arquiva todas as chaves criadas para ele em poucos segundos e não pode ser desfeito. O histórico fica preservado para relatórios, mas as chaves deixam de funcionar. Arquive um workspace só quando o ambiente de fato acabou.
Há ainda um workspace criado automaticamente, o Claude Code workspace, que separa o tráfego do Claude Code do resto. Ele cria uma chave por usuário no primeiro login, e essas chaves não podem ser criadas manualmente pelo console. A documentação também diz que arquivá-lo desativa o login do Claude Code por cobrança do console para a organização inteira.
3. O que cada chave pode fazer
Uma chave tem dois atributos que definem o alcance dela: o escopo e o dono. O escopo diz em quais workspaces a chave funciona. Uma chave criada com escopo de um único workspace só funciona ali, e as requisições feitas com ela não precisam informar o identificador do workspace. Uma chave sem escopo fixo, usada por pessoa ou conta de serviço com acesso a vários workspaces, exige que cada requisição informe o cabeçalho anthropic-workspace-id com o identificador do workspace de destino. A documentação mostra o caso de erro: uma requisição feita com uma chave que não tem escopo, sem o cabeçalho, recebe 400 com invalid_request_error, e a mensagem diz que o identificador é obrigatório. Se o workspace não existe ou a conta não tem acesso a ele, a resposta é 404 com not_found_error, a mesma resposta de qualquer workspace desconhecido. Essa uniformidade é intencional, porque não revela quais workspaces existem.
O dono define quando a chave deixa de valer. Uma chave pessoal age com as permissões do seu usuário, e a documentação diz que ela para de funcionar quando você perde acesso à organização ou, no caso de chave de um único workspace, ao workspace. Ao sair da organização, as chaves pessoais são arquivadas, e se você for convidado de novo precisa criar outras. Uma chave de conta de serviço para de funcionar quando a conta é arquivada ou, no caso de chave de um único workspace, quando a conta é removida dele. Ela continua funcionando mesmo que quem a criou saia da organização, porque a conta é que é a identidade. A tabela resume os três tipos.
| Tipo de chave | Age como | Para de funcionar quando |
|---|---|---|
| Pessoal | O usuário, com as permissões do papel dele | Ele perde acesso à organização ou ao workspace da chave. |
| Conta de serviço | A conta de serviço, com acesso aos workspaces que ela recebeu | A conta é arquivada ou, em chave de um workspace, é removida dele. |
| Workspace (legado) | Ninguém: pertence ao workspace de criação | Expira, é desativada ou apagada, ou o workspace é arquivado. |
A chave de administração merece atenção separada. A API de administração (Admin API) aceita uma chave de Admin, uma chave pessoal ou de conta de serviço que não tenha escopo de workspace, mas não aceita chave de workspace. A documentação de workspaces diz que as operações de workspace e de membros são feitas com essa API. Uma chave de administração dentro do código da aplicação é a pior combinação possível, porque ela controla membros, workspaces e limites, e não só as chamadas ao modelo. O certo é deixar a administração num processo separado, com credencial própria e guardada com mais rigor.
4. Menor privilégio
O princípio do menor privilégio diz que cada identidade deve ter só as permissões de que precisa, pelo tempo em que precisa, no lugar em que precisa. A justificativa é a conta do estrago: quando uma credencial vaza, o dano que ela pode causar é igual ao que ela pode fazer. Uma chave com acesso a todos os workspaces, sem expiração e de um administrador, é uma chave cujo vazamento pode, em teoria, causar o pior dos cenários. A mesma chave limitada a um workspace de testes, com expiração curta, causa um dano pequeno e bem delimitado.
A documentação não usa essa expressão, então a aplicação do princípio aqui é uma leitura dos mecanismos que ela descreve. Esses mecanismos são quatro. O primeiro é uma chave por integração e por ambiente, criada com escopo de um único workspace sempre que possível. O segundo é a expiração, que deve ser escolhida na criação, porque a documentação diz que ela não pode ser alterada depois. As predefinições são 3 horas, 1 dia, 7 dias e 30 dias, há duração personalizada, e a opção “Nunca” existe para quem guarda a chave num gerenciador de segredos e a rotaciona por conta própria. Uma chave de teste de uma tarde não precisa viver um mês. O terceiro é o papel de cada pessoa: quem só experimenta no playground recebe o papel de Workspace User, quem cria chaves recebe o de Developer, e só quem administra o workspace recebe o de Admin. O quarto é o limite de gasto por workspace, que limita o dano em dinheiro mesmo quando nada mais impede o uso indevido.
Há um ponto de disciplina que a documentação sugere indiretamente. Uma chave pessoal de um desenvolvedor não deve estar no código de um serviço compartilhado, porque ela age como essa pessoa e quebra quando ela sai. Uma chave de conta de serviço resolve esse caso, e a própria documentação manda pedir ao administrador da organização a criação dessa conta quando a carga é compartilhada ou automatizada.
5. Onde guardar segredos
A documentação de autenticação diz, de forma direta, que as chaves devem ser armazenadas num gerenciador de segredos. Esse é o lugar onde o segredo tem controle de acesso, histórico de quem leu e uma forma de trocar o valor sem mexer no código. Em muitas equipes, esse papel é cumprido pelo cofre da nuvem ou por um serviço dedicado de segredos. A aula não recomenda um produto específico, porque a escolha depende da infraestrutura de cada time.
Entre o gerenciador e o processo que faz a chamada existe um passo intermediário: a variável de ambiente em tempo de execução. O SDK oficial lê a variável ANTHROPIC_API_KEY quando você não passa a chave no construtor, e isso é o que mantém o segredo fora do arquivo de código. Em um servidor, a plataforma ou o próprio gerenciador injeta o valor no processo quando ele sobe, e o código-fonte nunca contém o valor. O código fica idêntico em todos os ambientes, e só o valor muda.
import anthropic
cliente = anthropic.Anthropic() # lê ANTHROPIC_API_KEY do ambiente
O comportamento desse código sem a variável foi testado nesta sessão, em 18/10/2026, com o SDK anthropic na versão 1.15.0. Usei um servidor local que registra os cabeçalhos recebidos, e um valor fictício no formato sk-ant-.... Nenhuma chamada saiu para a rede e nenhuma chave real foi usada. O primeiro resultado mostra o que acontece quando a variável não existe.
ANTHROPIC_API_KEY definida: False
cliente criado, sem erro na construção
Esse resultado merece atenção, porque contraria a intuição de que a aplicação falha na subida. O cliente é criado sem reclamar. A falha só aparece na primeira chamada, e ela acontece antes de qualquer pacote sair pela rede. A exceção é um TypeError do próprio SDK, com a mensagem de que o método de autenticação não pôde ser resolvido, e o servidor não recebe nada. Quem procura o problema no log do servidor da API não o encontra, porque a requisição nunca chegou lá. O diagnóstico certo começa na aplicação.
O segundo resultado mostra o caminho feliz, com a variável definida. A mesma chamada chega ao servidor com o cabeçalho x-api-key preenchido.
servidor recebeu x-api-key=presente authorization=ausente
chamada aceita
Por que nunca no código ou no repositório? Porque um segredo versionado não se apaga de verdade. Ele fica no histórico do git mesmo depois de removido do arquivo atual, é copiado para cada clone e cada fork, e pode aparecer em capturas de tela, em logs de depuração e em mensagens de revisão de código. Um arquivo .env no repositório tem o mesmo problema, e por isso ele deve estar no .gitignore. Para testar essa armadilha, criei um repositório de teste com duas chaves fictícias, uma num arquivo Python e outra num .env, e rodei um varredor simples que procura o prefixo sk-ant- em todos os arquivos.
import pathlib
import re
import sys
PADRAO = re.compile(r"sk-ant-[A-Za-z0-9_-]{8,}")
def mascarar(valor: str) -> str:
return f"{valor[:7]}...{valor[-4:]}"
raiz = pathlib.Path(sys.argv[1])
achados = 0
for arquivo in sorted(raiz.rglob("*")):
if not arquivo.is_file():
continue
texto = arquivo.read_text(errors="ignore")
for numero, linha in enumerate(texto.splitlines(), start=1):
for achado in PADRAO.findall(linha):
achados += 1
print(f"{arquivo.relative_to(raiz)}:{numero}: {mascarar(achado)}")
print(f"total de achados: {achados}")
Saída real:
.env:1: sk-ant-...0000
src/cliente.py:2: sk-ant-...0000
total de achados: 2
O varredor mostra só o prefixo e os últimos caracteres, para que o próprio relatório não vire um novo vazamento. Ele é útil, mas tem limite: procura só o formato conhecido e não entende contexto. Ferramentas de varredura de segredos existem para o histórico do git e para o pipeline de integração contínua, e uma verificação dessas deve rodar antes de qualquer merge. Não consultei a documentação dessas ferramentas para esta aula, então não descrevo detalhes delas aqui.
6. Rotação e vazamento
Rotacionar uma chave é trocá-la por outra de forma planejada. A documentação não define intervalo recomendado de rotação, e essa decisão fica com a equipe. O que a documentação exige é que os segredos sejam trocados periodicamente, e que chaves suspeitas de vazamento sejam desativadas ou apagadas. Na prática, a equipe deve escolher um intervalo, registrá-lo e cumpri-lo. A aula não inventa um número, porque nenhum número oficial foi encontrado.
Por que rotacionar se nada deu errado? Porque a rotação limita o tempo que um vazamento não detectado continua útil para quem o encontrou. Uma chave trocada a cada trimestre fica no máximo três meses no caminho de um eventual atacante, e uma chave que nunca mudou pode funcionar por anos. A rotação também testa o processo. Uma equipe que nunca trocou uma chave descobre no dia de um vazamento que não sabe onde ela está, quais serviços a usam e como fazer o deploy de um valor novo. A expiração automática da chave faz parte dessa disciplina, porque a documentação diz que a Anthropic avisa o criador por e-mail antes do vencimento. O aviso sai 7 dias antes para chaves com duração de pelo menos 14 dias, e 1 dia antes para chaves com duração de pelo menos 7 dias. Chaves de vida mais curta vencem sem aviso, o que é mais um motivo para não contar com o e-mail como controle.
A rotação segue quatro passos, que a documentação descreve para a troca de chaves de workspace e que servem para qualquer troca. Primeiro você cria a chave nova, no escopo do workspace da integração. Depois faz o deploy dela no lugar onde a aplicação lê a variável. Em seguida confirma que as requisições passam a funcionar. Só então apaga a antiga. A ordem é a parte que importa, porque apagar antes de confirmar deixa a aplicação sem chave válida, e a documentação não tem um caminho de volta para uma chave apagada.
Quando uma chave vaza, a sequência muda de natureza. A documentação manda desativar ou apagar qualquer chave suspeita, e a diferença entre as duas ações é o que decide a ordem. Desativar é reversível: a chave fica no estado inactive e pode ser reativada. Apagar é definitivo: a chave vira archived e não volta. Por isso, o primeiro movimento é desativar. Isso interrompe o uso indevido sem destruir a prova que a investigação vai precisar. A documentação não informa quanto tempo leva para a desativação valer em todas as requisições, e essa lacuna deve ser tratada como incerta no plano de resposta. Depois de desativar, a equipe cria uma chave nova, faz o deploy, confirma o funcionamento e só então apaga a chave vazada. Para a investigação, a documentação de workspaces mostra o relatório de uso agrupado por workspace, pela Usage and Cost API, o que ajuda a ver se o consumo anormal estava naquele workspace. Não há na documentação lida um relatório de uso por chave, então não afirmo que ele exista.
A figura resume a ordem dos passos da rotação, com o caminho de falha que a pressa costuma produzir.
Leia a figura de cima para baixo. O caminho da troca segura desce pela coluna da esquerda: criar a nova, implantar, confirmar, e só depois apagar a antiga. O losango é o ponto de decisão. Se as requisições não funcionam, o caminho segue para a direita e termina em “manter a antiga”, que é o lugar certo para diagnosticar o deploy, porque a chave antiga ainda existe e ainda funciona. A seta pontilhada que sai de “implantar” mostra o atalho que causa o problema: apagar sem confirmar. Ela termina num X vermelho, porque é esse o ponto em que a aplicação pode ficar sem chave válida, e a documentação não oferece como recuperar uma chave apagada.
7. O que nunca entra em prompt, log ou resposta
Depois de entender onde o segredo mora, falta a pergunta sobre o que ele não pode tocar. Três fluxos da aplicação atravessam texto livre e precisam ficar limpos: o prompt que vai para o modelo, o log que alguém vai ler e a resposta que o usuário ou outro sistema recebe. Em todos eles, um segredo que entra vira cópia que você não controla.
O prompt é o caminho menos óbvio. Tudo o que está no contexto da requisição pode ser repetido pelo modelo na resposta, e a requisição trafega pelo serviço da Anthropic. Se a chave entra no prompt, ela sai do seu controle e pode voltar em uma resposta que o usuário final lê. Essa é uma limitação de desenho, e não um detalhe de instrução: o modelo não tem como saber que um valor é segredo se você o colocou no texto que ele lê. A regra útil é simples. Se o segredo não está no contexto, o modelo não consegue repeti-lo.
O mesmo vale para ferramentas. Uma ferramenta que lê um arquivo de configuração e devolve o conteúdo ao modelo está colocando a chave no contexto, mesmo que ninguém a tenha escrito no prompt. Por isso o retorno de ferramenta precisa ser filtrado, e as ferramentas devem devolver só o que o modelo precisa para decidir.
O log é o caminho mais comum de vazamento. Logs são copiados para vários lugares, lidos por muita gente e guardados por muito tempo. Um log de depuração que imprime o cabeçalho completo da requisição leva a chave para todos esses lugares de uma vez. A regra prática é nunca registrar cabeçalhos de autenticação, e se for necessário mostrar a credencial, mostrar só a forma mascarada, como o varredor da seção 5 faz. Os identificadores que a documentação descreve como tais podem entrar no log sem problema. O request-id da resposta e o cabeçalho anthropic-workspace-id servem para suporte e para correlacionar uma chamada com o workspace que a executou. Não verifiquei se as mensagens de erro do SDK ecoam cabeçalhos, e por isso o log de erro deve passar pelo mesmo filtro dos logs comuns.
A resposta é o último caminho. O que o modelo devolve ao usuário ou a outro sistema pode incluir qualquer coisa que estava no contexto. Além disso, a resposta deve ser tratada como dado que pode ser exibido, copiado e reencaminhado, e nenhum desses usos é controlado pela sua aplicação. A chave jamais deve aparecer no texto de uma resposta, mesmo que a aplicação ache que o usuário já a conhece.
Vale a mesma regra para outros segredos, como senha de banco, token de outro serviço, chave de Admin API e credenciais de nuvem. A chave da Anthropic é só o caso mais visível deles. Uma aplicação com RAG, agente ou ferramentas tem muito mais caminhos para um segredo entrar no contexto, e cada caminho precisa ser revisado.
Parte 2: a prática
8. Erros comuns e boas práticas
O primeiro erro é colocar a chave no código, mesmo que seja “só para testar”. Um teste que passa a valer no próximo commit deixa a chave no histórico. A correção é a variável de ambiente desde o primeiro dia, porque o código que lê a variável é o mesmo em todos os ambientes e não precisa mudar quando a chave muda.
O segundo erro é usar a mesma chave em desenvolvimento, homologação e produção. Quando uma chave única vaza, o vazamento vale para tudo, e a troca precisa acontecer em todos os lugares ao mesmo tempo. Uma chave por ambiente e um workspace por ambiente limitam o estrago a um ambiente, e permitem trocar a de teste sem parar a produção.
O terceiro erro é criar a chave com expiração “Nunca” sem ter um processo de rotação. A opção existe para quem gerencia a troca, e sem o processo ela vira uma chave eterna. Quem escolhe “Nunca” precisa ter um calendário de rotação e um lugar onde a chave esteja registrada.
O quarto erro é usar uma chave pessoal num serviço compartilhado. Ela funciona enquanto a pessoa estiver na organização, e quebra no dia em que ela sai, em produção. A conta de serviço existe para isso.
O quinto erro é achar que desativar e apagar são a mesma coisa. Desativar é a ação de contenção, porque é reversível e corta o uso. Apagar é a ação de encerramento, porque é definitiva. Uma equipe que apaga a chave antes de desativar, e depois descobre que ela ainda era usada por um serviço esquecido, não tem como voltar atrás.
O sexto erro é deixar a chave de Admin API dentro da aplicação. Ela controla workspaces e membros, e uma aplicação comprometida com essa chave pode mudar quem tem acesso à organização. A administração deve ficar fora do caminho de requisições do produto.
O sétimo erro é arquivar um workspace achando que ele só some da tela. A documentação diz que o arquivamento desativa as chaves em poucos segundos e não pode ser desfeito. Antes de arquivar, liste as chaves e as integrações que dependem delas.
Como boas práticas, a lista é curta. Use uma chave por integração e um workspace por ambiente. Escolha a expiração na criação, pensando no uso real. Guarde o valor no gerenciador de segredos e injete-o como variável de ambiente. Mantenha varredura de segredos no pipeline. Defina um intervalo de rotação e registre-o. Tenha um plano escrito de resposta a vazamento que comece por desativar. Nunca registre cabeçalhos de autenticação, e nunca coloque segredos no contexto do modelo.
9. Exercícios
- Liste as chaves da sua organização, ou de um projeto de teste, e para cada uma responda: em qual workspace ela funciona, qual é o dono e quando expira. Se alguma não tiver dono ou expiração, escreva por quê.
- Rode o script de
chave_ambientecom a variável definida e sem ela. Confirme que a falha sem chave acontece antes da rede, e explique por que isso muda onde você procura o erro. - Crie um repositório de teste com uma chave fictícia num arquivo de código e num
.env. Rode o varredor da seção 5 e confirme que ele encontra os dois. Depois adicione o.envao.gitignoree veja o que muda, e o que não muda, no histórico. - Escreva um plano de resposta a vazamento de uma página, com a ordem: desativar, criar a nova, implantar, confirmar, apagar. Para cada passo, diga quem faz e onde registra a ação.
- Defina, para um projeto seu, o intervalo de rotação e o motivo da escolha. Diga o que acontece se o intervalo for cumprido com atraso.
- Revise um log de depuração do seu projeto e marque os campos que poderiam conter credenciais. Depois troque o registro por uma forma mascarada.
10. Glossário
| Termo | Significado |
|---|---|
| Chave de API | Segredo que identifica a conta na API. Vai no cabeçalho de autenticação, nunca no código. |
| Identidade | Quem a chamada representa do ponto de vista da API: uma pessoa, uma conta de serviço ou um workspace. |
| Workspace | Área de trabalho dentro da organização, com membros, chaves e limites próprios. |
| Default Workspace | Workspace criado com a organização, que não pode ser renomeado, arquivado nem apagado. |
| Escopo de chave | Os workspaces em que uma chave funciona. Chave de um workspace só funciona nele. |
| Chave pessoal | Chave que age com as permissões de um usuário e para quando ele sai da organização. |
| Conta de serviço | Identidade gerenciada pela organização para integrações compartilhadas e CI. |
| Chave de workspace | Modelo legado de chave, sem dono, que pertence ao workspace de criação. |
| Workload Identity Federation | Troca de um token do provedor de identidade por um token de curta duração, sem chave de longa duração. |
| Menor privilégio | Princípio de dar a cada identidade só as permissões e o tempo de que precisa. |
| Gerenciador de segredos | Serviço que guarda segredos com controle de acesso, histórico e troca de valor. |
| Variável de ambiente | Valor injetado no processo quando ele sobe, lido pelo SDK a partir de ANTHROPIC_API_KEY. |
| Rotação | Troca planejada de uma chave por outra, com passos de criação, implantação, confirmação e exclusão. |
| Desativar | Ação reversível que impede o uso de uma chave, com estado inactive. |
| Apagar | Ação definitiva que arquiva a chave, com estado archived. |
| Expiração | Data de vencimento escolhida na criação da chave, que não pode ser alterada depois. |
| Admin API | API de administração de organização e workspaces, que exige chave própria de administração. |
11. Fontes
Consultadas em 18/10/2026, com os links oficiais.
- Autenticação e chaves (tipos de chave, escopo por workspace, expiração, aviso por e-mail, desativar e apagar, substituição de chave de workspace, cabeçalho
anthropic-workspace-id): https://platform.claude.com/docs/en/manage-claude/authentication - Workspaces (papéis, limites de gasto e de taxa por workspace, arquivamento, Claude Code workspace, uso de chaves por escopo, relatório de uso por workspace): https://platform.claude.com/docs/en/manage-claude/workspaces
- Página de como obter a chave, consultada apenas por resumo de busca, sem leitura integral: https://platform.claude.com/docs/en/get-api-key. O resumo indicou que a chave completa aparece uma única vez, na criação. Trate essa informação como não confirmada na página completa.
- SDK Python
anthropic, versão 1.15.0, instalado no ambiente de estudo em 18/10/2026. Os comportamentos de construção do cliente e de falha sem chave vêm do teste desta aula.
O que não ficou verificado, ou ficou com lacuna declarada:
- Intervalo recomendado de rotação. A documentação lida não traz um número, e a aula também não inventa um.
- Quanto tempo leva a desativação de uma chave para valer em todas as requisições. A documentação não informa.
- Existência de relatório de uso por chave. A documentação lida mostra relatório por workspace, e não por chave.
- Se as mensagens de erro do SDK ecoam cabeçalhos de autenticação. Não testei esse caso.
- Lista oficial de valores proibidos em prompt e log. A documentação lida não tem essa lista, e as regras da seção 7 são recomendações derivadas dos mecanismos descritos, não citações.
- Detalhes da Workload Identity Federation e da Admin API. Eles foram citados pela página de autenticação, mas as páginas específicas não foram lidas nesta sessão.
- Ferramentas de varredura de segredos. Não consultei a documentação delas, e a aula só cita a categoria.