--- title: Referência de WIF url: https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference description: Variáveis de ambiente, regras de validação, configuração de perfil e referência de erros para Workload Identity Federation. --- Esta página reúne as superfícies de configuração, restrições de validação e mapeamentos de erros para [Workload Identity Federation](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation). Para tutoriais de configuração, consulte os [guias de provedores](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation#identity-providers). ## Requisição de troca de token `POST /v1/oauth/token` aceita um corpo JSON usando a concessão `jwt-bearer` da [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523). O SDK constrói essa requisição para você a partir das [variáveis de ambiente](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#environment-variables); os exemplos de cURL em cada guia de provedor mostram o corpo bruto. | Campo | Obrigatório | Descrição | | -------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `grant_type` | Sim | Sempre `urn:ietf:params:oauth:grant-type:jwt-bearer`. | | `assertion` | Sim | O JWT OIDC emitido pelo seu provedor de identidade. | | `federation_rule_id` | Sim | ID com tag (`fdrl_...`) da regra de federação a ser avaliada. | | `organization_id` | Sim | UUID da sua organização Anthropic. | | `service_account_id` | Sim | ID com tag (`svac_...`) da conta de serviço de destino. | | `workspace_id` | Condicional | ID com tag (`wrkspc_...`) do workspace ao qual o token emitido será restrito. Obrigatório quando a regra está habilitada para mais de um workspace. Quando omitido, o servidor seleciona o único workspace habilitado da regra. O literal `default` também funciona para o Default Workspace da organização, mas está descontinuado; use o ID `wrkspc_...` desse workspace. | ## Resposta de troca de token `POST /v1/oauth/token` retorna uma resposta de token OAuth 2.0 padrão ([RFC 6749 §5.1](https://www.rfc-editor.org/rfc/rfc6749#section-5.1)): | Campo | Tipo | Descrição | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------- | | `access_token` | string | O token Anthropic de curta duração, prefixado com `sk-ant-oat01-...`. Passe-o como `Authorization: Bearer `. | | `token_type` | string | Sempre `Bearer`. | | `expires_in` | integer | Segundos até o token expirar. | | `scope` | string | O escopo OAuth concedido pela regra correspondente. | ## Variáveis de ambiente O SDK lê essas variáveis para realizar uma troca de token federada sem argumentos de construtor. | Variável | Obrigatória | Descrição | Exemplo | | ------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `ANTHROPIC_FEDERATION_RULE_ID` | Sim | ID com tag da regra de federação a ser avaliada. | `fdrl_...` | | `ANTHROPIC_ORGANIZATION_ID` | Sim | UUID da sua organização Anthropic. Encontre-o na página [Organization](https://platform.claude.com/settings/organization) (`platform.claude.com/settings/organization`) no Claude Console. | `00000000-0000-0000-0000-000000000000` | | `ANTHROPIC_IDENTITY_TOKEN_FILE` | Uma de `_TOKEN_FILE` ou `_TOKEN` | Caminho no sistema de arquivos para o JWT emitido pelo seu "identity provider" (provedor de identidade), ou IdP. O SDK relê esse arquivo a cada troca para que tokens projetados que são rotacionados em disco estejam sempre atualizados. | `/var/run/secrets/anthropic.com/token` | | `ANTHROPIC_IDENTITY_TOKEN` | Uma de `_TOKEN_FILE` ou `_TOKEN` | O JWT literal como string. Use quando sua plataforma injeta o token como variável de ambiente em vez de arquivo. | `eyJhbGciOiJSUzI1NiIs...` | | `ANTHROPIC_SERVICE_ACCOUNT_ID` | Sim | ID com tag da conta de serviço Anthropic de destino em nome da qual o token de acesso emitido atua. | `svac_...` | | `ANTHROPIC_WORKSPACE_ID` | Condicional | ID com tag do workspace ao qual o token emitido será restrito. Obrigatório quando a regra de federação está habilitada para mais de um workspace; opcional quando a regra está vinculada a um único workspace. O token emitido é restrito a esse workspace no momento da troca, portanto trocar de workspace exige uma nova troca. O literal `default` também funciona para o Default Workspace, mas está descontinuado; use o ID `wrkspc_...` dele. | `wrkspc_...` | | `ANTHROPIC_PROFILE` | Não | Nome de um [perfil de configuração](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#profile-configuration-file) a ser carregado. Tem precedência sobre as variáveis de ambiente de federação desta tabela. | `staging-profile` | O caminho de federação direto por variável de ambiente é ativado apenas quando `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` e um de `ANTHROPIC_IDENTITY_TOKEN_FILE` ou `ANTHROPIC_IDENTITY_TOKEN` estão todos definidos. `ANTHROPIC_WORKSPACE_ID` é lido junto, mas não controla a ativação. Uma variável definida como uma string vazia ainda ocupa seu lugar na cadeia de precedência de credenciais. Se `ANTHROPIC_API_KEY=""` for exportada, o SDK seleciona o caminho de chave de API com uma chave vazia em vez de cair para a federação. Remova a definição das variáveis de credencial não utilizadas em vez de deixá-las em branco. ### Precedência de credenciais O SDK resolve credenciais nesta ordem. A primeira fonte que produz uma credencial vence. | Ordem | Fonte | Notas | | ----- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 1 | Argumento de construtor (`api_key=`, `auth_token=`, `credentials=`) | Sempre sobrepõe todo o resto. | | 2 | `ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN` | Oculta a federação inteiramente. Remova a definição destas ao migrar de chaves de API. | | 3 | `ANTHROPIC_PROFILE` | Carrega `/configs/.json`. Um perfil nomeado ausente é um erro, não uma passagem adiante. | | 4 | Variáveis de ambiente de federação | `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`. | | 5 | Perfil ativo | Resolvido a partir de `/active_config`, recorrendo a um perfil chamado `default`. | Quando um perfil é carregado, as variáveis de ambiente preenchem quaisquer campos que o perfil omite, mas nunca sobrepõem campos que o perfil define explicitamente. Por exemplo, `ANTHROPIC_WORKSPACE_ID` preenche `workspace_id` apenas quando o perfil ativo não o define. ## Arquivo de configuração de perfil Um perfil é um arquivo de configuração nomeado que tanto o SDK quanto a CLI `ant` leem. Perfis permitem que você envie parâmetros de federação com sua imagem de contêiner ou alterne entre ambientes sem alterar o código. ### Diretório de configuração O SDK localiza o diretório de configuração nesta ordem: 1. `$ANTHROPIC_CONFIG_DIR` 2. `~/.config/anthropic` no Linux e macOS 3. `%APPDATA%\Anthropic` no Windows ### Perfil ativo O nome do perfil ativo é resolvido nesta ordem: 1. `$ANTHROPIC_PROFILE` 2. O conteúdo de `/active_config` (um arquivo de uma linha escrito por `ant profile activate `) 3. O nome literal `default` O Claude Code e o Claude Agent SDK respeitam essa mesma ordem de resolução, então um perfil de federação configurado aqui também autentica essas ferramentas sem configuração adicional. ### Layout de arquivos | Caminho | Conteúdo | Sensibilidade | | ----------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `/configs/.json` | `version`, o bloco `authentication`, `organization_id`, `workspace_id` e `base_url`. | Não secreto. Seguro para commitar ou incorporar em uma imagem. | | `/credentials/.json` | `version`, o `access_token` em cache, `expires_at` e (para login interativo) `refresh_token`. | Secreto. Escrito pelo SDK com modo `0600`. | Tanto o arquivo de configuração quanto o arquivo de credenciais carregam um campo string `version` de nível superior no formato `major.minor` (atualmente `"1.0"`). O SDK escreve este campo automaticamente para que versões futuras possam detectar e migrar formatos mais antigos; omita-o ao criar uma configuração manualmente e o SDK trata o arquivo como a versão atual. ### Exemplo de perfil de federação ```json configs/production.json { "version": "1.0", "authentication": { "type": "oidc_federation", "federation_rule_id": "fdrl_...", "service_account_id": "svac_...", "identity_token": { "source": "file", "path": "/var/run/secrets/anthropic.com/token" } }, "organization_id": "00000000-0000-0000-0000-000000000000", "workspace_id": "wrkspc_...", "base_url": "https://api.anthropic.com" } ``` Se `authentication.identity_token` for omitido, o SDK recorre a `ANTHROPIC_IDENTITY_TOKEN_FILE` ou `ANTHROPIC_IDENTITY_TOKEN` do ambiente. ## Escopos OAuth O `oauth_scope` que você define em uma regra de federação determina quais endpoints da API do Claude o token de acesso gerado pode chamar. | Escopo | Concede acesso a | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | Todos os endpoints não administrativos da API do Claude no workspace da regra: [Messages](https://platform.claude.com/docs/pt-BR/api/messages) (incluindo streaming e contagem de tokens), [Models](https://platform.claude.com/docs/pt-BR/api/models/list), [Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview) e suas sessões, [Files](https://platform.claude.com/docs/pt-BR/build-with-claude/files) e [Skills](https://platform.claude.com/docs/pt-BR/build-with-claude/skills-guide). Isso corresponde ao acesso que uma chave de API de workspace no mesmo workspace tem. | | `workspace:inference` | Os endpoints de inferência no workspace da regra: [Messages](https://platform.claude.com/docs/pt-BR/api/messages) (incluindo streaming e contagem de tokens), [Models](https://platform.claude.com/docs/pt-BR/api/models/list) e o [endpoint de chat compatível com OpenAI](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/libraries/openai-sdk). Use isso para cargas de trabalho que só precisam chamar o Claude e nunca precisam gerenciar Files, Skills ou outros recursos. | | `workspace:manage_tunnels` | A [API de túneis MCP](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-tunnels/reference#tunnels-api): criar, listar e obter túneis, registrar e arquivar certificados CA, revelar e rotacionar o token do túnel e arquivar túneis. A janela modal de criação de túnel do Console bloqueia este escopo quando você cria uma regra a partir dela. | | `org:admin` | Acesso total à [Admin API](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api) (membros da organização, convites, workspaces, chaves de API e o restante). Um token OAuth `org:admin` só pode criar ou modificar regras com escopo `workspace:developer` ou `workspace:inference`, e não pode atualizar um emissor que respalda uma regra com qualquer outro escopo; consulte as [restrições](https://platform.claude.com/docs/pt-BR/manage-claude/wif-admin-api#permissions-and-constraints). | Uma requisição a um endpoint fora do escopo do token retorna HTTP 403. Escopos mais granulares (por recurso, ou leitura versus escrita) não estão disponíveis atualmente. ### Limites de permissão O `oauth_scope` de uma regra de federação é um teto: o token gerado nunca pode excedê-lo. O `organization_role` da conta de serviço de destino (`developer` ou `admin`) determina quais escopos são concedíveis, então uma regra que concede `org:admin` deve ter como destino uma conta de serviço com `organization_role=admin`. As permissões efetivas são a interseção do escopo da regra e do papel da conta de serviço. | `oauth_scope` da regra | `organization_role` da conta de serviço | Permissões efetivas | | ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | `admin` | Acesso à API do Claude apenas no workspace da regra. O escopo limita o token abaixo do papel. | | `org:admin` | `admin` | Acesso total à Admin API (membros da organização, convites, workspaces, chaves de API e o restante), menos as exceções do chamador OAuth; consulte as [restrições](https://platform.claude.com/docs/pt-BR/manage-claude/wif-admin-api#permissions-and-constraints). | ## Regras de validação A Anthropic impõe essas restrições quando você cria ou atualiza emissores e regras, e ao verificar um JWT recebido no momento da troca. Para detalhes completos dos parâmetros e esquemas de resposta, consulte a [referência da API de contas de serviço](https://platform.claude.com/docs/pt-BR/api/organization/service_accounts), a [referência da API de emissores de federação](https://platform.claude.com/docs/pt-BR/api/organization/federation/issuers) e a [referência da API de regras de federação](https://platform.claude.com/docs/pt-BR/api/organization/federation/rules). ### Campos de recurso | Campo | Restrição | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` de emissor, regra e conta de serviço | Deve corresponder a `^[a-z0-9-]+$`, comprimento de 1 a 255 caracteres. | | `workspace_id` | Obrigatório na criação, a menos que `applies_to_all_workspaces` seja verdadeiro. O workspace (`wrkspc_...`) cuja cota, faturamento e limites de taxa se aplicam aos tokens gerados sob esta regra. Deve ser um workspace na mesma organização, e a conta de serviço de destino deve ser membro desse workspace. | | `applies_to_all_workspaces` | Booleano. Defina `true` para habilitar a regra em todos os workspaces da organização em vez de nomear um; este ou `workspace_id` é obrigatório na criação. | | `token_lifetime_seconds` | Inteiro entre `60` e `86400` (1 minuto a 24 horas). Padrão `3600`. Valores fora deste intervalo são rejeitados no momento da requisição. Consulte [Tempo de vida e renovação do token](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation#token-lifetime-and-refresh). | ### Campos de URL Os campos `issuer_url`, `jwks.discovery_base` e `jwks.url` são validados: | Restrição | Detalhe | | --------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Esquema | Deve ser `https`. | | Porta | Deve ser `443` (explícita ou padrão). | | Host | Deve ser um nome de host DNS público para seu provedor OIDC. Deve resolver para endereços IP públicos; literais de IP não são aceitos. | Falhas de validação de URL retornam `400 invalid_request_error` com o nome do campo como prefixo na mensagem de erro (por exemplo, `issuer_url: url must use https scheme`). As restrições de URL se aplicam apenas a URLs que a Anthropic acessa. Nos modos JWKS `explicit_url` e `inline`, e no modo `discovery` quando `jwks.discovery_base` está definido, o `issuer_url` é comparado com a claim `iss` do JWT como uma string e nunca é buscado, então pode referenciar um nome de host interno ou porta não padrão. ### Verificação de JWT | Restrição | Detalhe | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tamanho máximo | O JWT `assertion` deve ter no máximo 16 KiB. | | Algoritmo de assinatura | Somente algoritmos assimétricos (famílias RSA e ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512) são aceitos. HMAC (`HS256`, `HS384`, `HS512`) e `none` são rejeitados. | | ID da chave | O cabeçalho do JWT deve conter um `kid` que corresponda a uma chave no JWKS do emissor. Tokens sem `kid` são rejeitados. | | Claims obrigatórias | `sub` deve estar presente. `iat` deve estar presente e não estar no futuro. `exp` deve estar presente e estar no futuro. | | Uso único | Uma asserção que contém uma claim `jti` só pode ser trocada uma vez por emissor: repetir uma troca com o mesmo `jti` é rejeitado como replay. O campo `check_jti` do emissor (habilitado por padrão) controla essa verificação; asserções sem uma claim `jti` não estão sujeitas a ela. Consulte a [referência da API de emissores de federação](https://platform.claude.com/docs/pt-BR/api/organization/federation/issuers). | | Tempo de vida máximo | O tempo de vida do token (`exp` menos `iat`) não deve exceder o máximo configurado do emissor (1 hora por padrão, configurável para cada emissor no Claude Console). | | Desvio de relógio | Uma tolerância de 30 segundos é aplicada a `exp`, `nbf` e `iat`. | ## Semântica de correspondência de regras O bloco `match` de uma regra de federação determina se um JWT recebido é aceito. Todos os campos preenchidos são avaliados com semântica AND: o JWT deve satisfazer cada correspondente preenchido. Pelo menos um de `subject_prefix`, `claims` ou `condition` deve ser definido; um bloco `match` que contém apenas `audience` (ou nenhum correspondente) é rejeitado. Isso protege contra regras que aceitariam todos os tokens de um emissor. | Correspondente | Tipo | Semântica | | ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subject_prefix` | string | Correspondência exata com a claim `sub` do JWT. Um `*` final o torna uma correspondência de prefixo (o valor `sub` deve começar com os caracteres antes do `*`). Sensível a maiúsculas e minúsculas. | | `audience` | string | A claim `aud` do JWT deve conter esta string exata. Quando `aud` é um array, qualquer elemento que corresponda exatamente satisfaz a verificação. | | `claims` | map\ | Cada chave é um nome de claim de nível superior e cada valor é o valor de string exato exigido. Para claims aninhadas, numéricas, booleanas ou complexas como listas e mapas, use `condition` com uma expressão CEL. | | `condition` | string (CEL) | Uma expressão [CEL](https://cel.dev/) que deve avaliar como `true`. | ### Ambiente de avaliação CEL A expressão `condition` tem acesso a uma única variável: | Variável | Tipo | Conteúdo | | -------- | ---- | ---------------------------------------------------------------------------------------------------------- | | `claims` | map | O conjunto completo de claims decodificadas do JWT. Objetos aninhados são acessíveis como mapas aninhados. | Exemplo: ```text wrap claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"] ``` Condições CEL são limites de segurança. Uma expressão que avalia como `true` para mais entradas do que o pretendido concede acesso mais amplo do que o pretendido. Prefira os correspondentes estáticos quando eles expressarem sua restrição. ## Erros ### Erros de troca de token `POST /v1/oauth/token` retorna erros no [formato de erro da API](https://platform.claude.com/docs/pt-BR/api/errors) padrão. O SDK relata uma falha de troca como `WorkloadIdentityError` (ruby: `Anthropic::Credentials::WorkloadIdentityError`; go: `error`; java: `UnexpectedStatusCodeException`; csharp: `WorkloadIdentityException`; php: `OAuthException`), que fornece o status HTTP e os detalhes do erro do corpo da resposta. O ID da requisição está no erro em Python, TypeScript e Ruby, e nos cabeçalhos de resposta da exceção em Java. Em Go, ele está apenas na mensagem do erro, porque o tipo do erro está em um pacote interno; os erros de C# e PHP não o incluem. | Status | Erro | Causa | Resolução | | ------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | `invalid_request_error` | `federation_rule_id` está malformado ou um campo obrigatório da requisição está ausente. | Verifique o ID `fdrl_` e se o corpo da requisição inclui todos os campos obrigatórios. | | 400 | `invalid_request_error` | `workspace_id` está presente, mas não é um ID `wrkspc_...` bem formado ou o literal `default`. | Corrija o valor de `workspace_id`; a mensagem de resposta nomeia o formato esperado. | | 401 | `authentication_error` | A claim `iss` do JWT não é exatamente igual ao `issuer_url` registrado. | Compare byte a byte, incluindo barras finais e esquema: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`. | | 401 | `authentication_error` | A busca do JWKS falhou, o JWKS está desatualizado ou o JWT foi assinado com uma chave que não está no JWKS. | Para o modo `inline`, atualize o emissor com as chaves rotacionadas. Para `discovery` e `explicit_url`, confirme que o endpoint JWKS está acessível na porta 443; se o emissor rotacionou recentemente sua chave de assinatura, consulte [Rotação e cache de chaves](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#key-rotation-and-caching). | | 401 | `authentication_error` | A claim `exp` do JWT está no passado (além da janela de desvio de 30 segundos). | Confirme que seu provedor de identidade está projetando um token novo e que o SDK está relendo o arquivo de token. | | 401 | `authentication_error` | O JWT foi verificado, mas suas claims não satisfazem o bloco `match` da regra. | Decodifique o JWT e compare cada claim com a regra. `subject_prefix` é sensível a maiúsculas e minúsculas. `audience` requer uma correspondência exata de elemento. | | 401 | `authentication_error` | O `federation_rule_id` não existe, está arquivado ou o JWT não está autorizado para ele (consolidado para evitar enumeração). | Confirme o ID da regra no Claude Console e que a regra não foi arquivada. | | 401 | `authentication_error` | A regra de federação está habilitada para mais de um workspace e a requisição omite `workspace_id`. A entrada do histórico de autenticação mostra o motivo `workspace_id_required`. | Defina `ANTHROPIC_WORKSPACE_ID` (ou o campo de corpo `workspace_id` em uma requisição bruta) para o ID `wrkspc_...` ao qual você deseja limitar o escopo do token. Consulte [Requisição de troca de token](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#token-exchange-request). | Toda negação de asserção retorna o mesmo `401` `authentication_error` opaco com a mensagem fixa `Authentication failed`, independentemente de qual verificação falhou; um erro distinguível permitiria que um chamador sondasse a configuração da regra. O motivo da negação é registrado na entrada da tentativa no [histórico de autenticação](https://platform.claude.com/settings/workload-identity-federation?tab=history) no Claude Console, por exemplo `match_subject_prefix` quando a claim `sub` não satisfaz o `subject_prefix` da regra, ou `workspace_id_required` quando a regra abrange vários workspaces e a requisição não nomeia nenhum. Requisições rejeitadas antes que a organização da regra seja corroborada (a família `400 invalid_request_error` acima) não deixam entrada no histórico; suas mensagens de resposta indicam o problema diretamente. Um `401` sem entrada correspondente no histórico geralmente significa que o próprio `federation_rule_id` não foi reconhecido. ### Falhas comuns do lado do SDK | Sintoma | Causa | Resolução | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | O SDK relata "no credentials" em vez de trocar | Um de `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` ou `ANTHROPIC_IDENTITY_TOKEN[_FILE]` não está definido e nenhum perfil está ativo. | Defina todas as quatro variáveis ou configure um perfil. | | O SDK autentica com uma chave de API em vez de federar | `ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN` está definido e vence a precedência. | Remova a definição da variável de chave ou token. | | `FileNotFoundError` na primeira requisição | O caminho em `ANTHROPIC_IDENTITY_TOKEN_FILE` não existe. O SDK abre o arquivo de forma preguiçosa no momento da troca. | Confirme que o volume de token projetado está montado e que o caminho corresponde. | | A troca de token é bem-sucedida, mas uma requisição à API do Claude retorna 403 | O escopo do token gerado não concede acesso a esse endpoint. | Verifique o `oauth_scope` da regra em relação aos [Escopos OAuth](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#oauth-scopes). | | A autenticação falha com credencial vazia | Uma variável de ambiente de credencial é exportada, mas definida como uma string vazia. Valores vazios ainda vencem seu lugar de precedência. | Remova a definição da variável com `unset VAR` em vez de `VAR=""`. | ## Solucionar uma troca com falha Uma resposta `401` `authentication_error` é intencionalmente opaca e sua mensagem é sempre `Authentication failed`; o motivo da negação é registrado no histórico de autenticação, não na resposta. Comece pela [página de histórico de autenticação](https://platform.claude.com/settings/workload-identity-federation?tab=history) no Claude Console. Tentativas de troca recentes revelam o emissor e a regra que foram avaliados, as claims do JWT que foram inspecionadas e qual etapa de validação falhou, o que geralmente encurta as verificações a seguir. Uma falha opaca comum é uma asserção reproduzida: uma asserção que carrega uma claim `jti` pode ser [trocada apenas uma vez](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#jwt-verification), então uma carga de trabalho que reenvia o mesmo JWT (um loop de retry, ou uma renovação que relê um token não rotacionado) é rejeitada na segunda troca. A página de histórico de autenticação mostra essas tentativas com o motivo `jti_reused`; a correção é gerar uma asserção nova para cada troca. Se você ainda precisar depurar a partir do próprio JWT, trabalhe nessas verificações em ordem: Decodifique a asserção que você enviou para poder comparar cada claim com a configuração do seu emissor e regra: ```bash cURL jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT" ``` A claim `iss` decodificada deve ser igual ao `issuer_url` registrado byte a byte, incluindo esquema, porta e qualquer barra final. Uma incompatibilidade em um único caractere falha na verificação. A claim `aud` decodificada deve conter o valor `audience` da regra como uma correspondência exata. Quando `aud` é um array, um elemento deve corresponder exatamente. Compare `sub` com o `subject_prefix` da regra (sensível a maiúsculas e minúsculas; um `*` final é uma correspondência de prefixo, qualquer outra coisa é exata). Compare cada chave no mapa `claims` da regra com a claim de nível superior de mesmo nome. `exp` deve estar no futuro e `nbf`/`iat` devem estar no passado, dentro da janela de desvio de 30 segundos. Se o relógio do host da carga de trabalho desviou, um token de outra forma válido é rejeitado. Para o modo `discovery`, busque `/.well-known/openid-configuration` por HTTPS público na porta 443 e confirme que `jwks_uri` resolve. Para `explicit_url`, busque a URL do JWKS diretamente. Para `inline`, confirme que a chave de assinatura do emissor não rotacionou desde que você registrou as chaves. Se o emissor rotacionou sua chave de assinatura e imediatamente começou a assinar com ela, as trocas podem falhar por até um minuto enquanto o cache JWKS da Anthropic é atualizado. Consulte [Rotação e cache de chaves](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#key-rotation-and-caching). ## Modos de fonte JWKS Quando você registra um emissor de federação, o campo `jwks` controla como a Anthropic obtém as chaves públicas usadas para verificar assinaturas de JWT desse emissor. É uma união discriminada com chave em `type`: | `jwks.type` | Formato de `jwks` | Comportamento | Use quando | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `discovery` (padrão) | `{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` é opcional; defina-o quando a URL de discovery difere de `issuer_url`) | A Anthropic busca `/.well-known/openid-configuration`, lê `jwks_uri` do documento de discovery e busca o JWKS de lá. | Seu IdP serve um documento de discovery OIDC padrão na internet pública. A maioria dos provedores gerenciados (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) suporta isso. | | `explicit_url` | `{ "type": "explicit_url", "url": "https://..." }` | A Anthropic busca o JWKS diretamente de `url`. O `issuer_url` é usado apenas para comparação de string com a claim `iss` do JWT e nunca é acessado. | Seu IdP não serve um documento de discovery, ou o discovery é apenas interno, mas o JWKS é publicamente acessível. | | `inline` | `{ "type": "inline", "keys": [...] }` | Você fornece o array de objetos JWK inline (o array `keys` do documento JWKS, não o objeto wrapper). A Anthropic não faz nenhuma requisição de saída. O `issuer_url` é usado apenas para comparação de `iss`. | Ambientes isolados (air-gapped), clusters Kubernetes autogerenciados com URLs de emissor internas ao cluster, ou quando você deseja controle explícito sobre a rotação de chaves. | A união discriminada torna os campos companheiros mutuamente exclusivos por construção. Tanto `discovery` quanto `explicit_url` também aceitam uma string `ca_cert_pem` opcional para emissores que servem TLS de uma CA privada. ### Rotação e cache de chaves Nos modos `discovery` e `explicit_url`, a Anthropic armazena em cache o JWKS buscado. Se seu provedor de identidade publica uma nova chave de assinatura e imediatamente começa a assinar tokens com ela, as trocas que apresentam esses tokens podem falhar com um erro de assinatura por até 1 minuto enquanto o cache é atualizado. Para evitar essa janela, publique uma nova chave de assinatura no JWKS pelo menos 15 minutos antes de seu provedor de identidade começar a assinar tokens com ela, e mantenha a chave substituída no JWKS até que os tokens que ela assinou tenham expirado. Provedores de identidade gerenciados normalmente seguem essa disciplina por conta própria. Se você opera seu próprio emissor (um cluster Kubernetes autogerenciado, um provedor de discovery OIDC SPIRE ou um servidor de autorização personalizado Okta com uma cadência de rotação configurada), confirme que sua política de rotação publica novas chaves antes do primeiro uso. No modo `inline` não há atualização automática de chaves. Quando seu provedor de identidade rotaciona suas chaves de assinatura, você deve atualizar a configuração do emissor com o novo JWKS ou todas as trocas de token falharão na verificação de assinatura.