--- 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 perfis e referência de erros para Workload Identity Federation. --- Esta página reúne as superfícies de configuração, as restrições de validação e os mapeamentos de erros para [Workload Identity Federation](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation). Para guias passo a passo de configuração, consulte os [guias de provedores](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation#identity-providers). ## Solicitaçã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 solicitaçã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 marcado (`fdrl_...`) da regra de federação a ser avaliada. | | `organization_id` | Sim | UUID da sua organização Anthropic. | | `service_account_id` | Sim | ID marcado (`svac_...`) da conta de serviço de destino. | | `workspace_id` | Condicional | ID marcado (`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 da 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, com prefixo `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ê estas 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 marcado 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 entre `_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 entre `_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 marcado da conta de serviço Anthropic de destino em nome da qual o "access token" (token de acesso) emitido atua. | `svac_...` | | `ANTHROPIC_WORKSPACE_ID` | Condicional | ID marcado 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áveis de ambiente só é ativado quando `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` e uma entre `ANTHROPIC_IDENTITY_TOKEN_FILE` ou `ANTHROPIC_IDENTITY_TOKEN` estão todas definidas. `ANTHROPIC_WORKSPACE_ID` é lida em conjunto, mas não condiciona a ativação. Uma variável definida como string vazia ainda pode ocupar sua posição na cadeia de precedência de credenciais. Remova a definição das variáveis de credenciais não utilizadas em vez de deixá-las em branco. ### Precedência de credenciais O SDK resolve as credenciais nesta ordem. A primeira fonte que fornecer uma credencial prevalece. | Ordem | Fonte | Observações | | ----- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 1 | Argumento do construtor (`api_key=`, `auth_token=`, `credentials=`) | Sempre substitui todo o resto. | | 2 | `ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN` | Oculta completamente a federação. Remova a definição delas ao migrar de chaves de API. | | 3 | `ANTHROPIC_PROFILE` | Carrega `/configs/.json`. Um perfil nomeado ausente é um erro, não uma passagem para a próxima fonte. | | 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`. | Na CLI `ant`, as configurações para [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed#authentication) têm prioridade abaixo das variáveis de ambiente de federação e acima do perfil ativo. As configurações são o projeto, o ID do workspace e a localização. Você as define com as flags `--google-cloud-*` ou com as variáveis `ANTHROPIC_GOOGLE_CLOUD_*`. A CLI usa essas configurações quando qualquer uma delas está definida. Com essas configurações, a CLI obtém sua credencial a partir das Google Application Default Credentials. Quando um perfil é carregado, as variáveis de ambiente preenchem quaisquer campos que o perfil omita, mas nunca substituem campos que o perfil define explicitamente. Por exemplo, `ANTHROPIC_WORKSPACE_ID` preenche `workspace_id` somente 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. Os perfis permitem que você distribua parâmetros de federação com sua imagem de contêiner ou alterne entre ambientes sem alterar 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` Claude Code e o Claude Agent SDK respeitam essa mesma ordem de resolução, portanto um perfil de federação configurado aqui também autentica essas ferramentas sem configuração adicional. ### Estrutura de arquivos | Caminho | Conteúdo | Sensibilidade | | ----------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `/configs/.json` | `version`, o bloco `authentication`, `organization_id`, `workspace_id` e `base_url`. | Não secreto. Seguro para fazer commit ou incluir 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 contêm um campo string `version` de nível superior no formato `major.minor` (atualmente `"1.0"`). O SDK escreve esse 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 tratará 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 Claude API o token de acesso emitido pode chamar. | Escopo | Concede acesso a | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | Todos os endpoints não administrativos da Claude API 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 possui. | | `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-o para cargas de trabalho que só precisam chamar 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 de 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 esse 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 sustenta 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 solicitaçã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 emitido nunca pode excedê-lo. O `organization_role` da conta de serviço de destino (`developer` ou `admin`) determina quais escopos podem ser concedidos, portanto 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 entre o escopo da regra e a função da conta de serviço. | `oauth_scope` da regra | `organization_role` da conta de serviço | Permissões efetivas | | ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | `admin` | Acesso à Claude API apenas no workspace da regra. O escopo limita o token abaixo da função. | | `org:admin` | `admin` | Acesso total à Admin API (membros da organização, convites, workspaces, chaves de API e o restante), exceto as exclusões para chamadores 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 aplica estas restrições quando você cria ou atualiza emissores e regras, e ao verificar um JWT recebido no momento da troca. Para detalhes completos de 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 recursos | Campo | Restrição | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` de emissor, regra e conta de serviço | Deve corresponder a `^[a-z0-9-]+$`, com comprimento de 1 a 255 caracteres. | | `workspace_id` | Obrigatório na criação, a menos que `applies_to_all_workspaces` seja true. O workspace (`wrkspc_...`) cuja cota, faturamento e limites de taxa se aplicam aos tokens emitidos sob esta regra. Deve ser um workspace da mesma organização, e a conta de serviço de destino deve ser membro desse workspace. | | `applies_to_all_workspaces` | Booleano. Defina como `true` para habilitar a regra em todos os workspaces da organização em vez de nomear um; este campo 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 desse intervalo são rejeitados no momento da solicitaçã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 o 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 string e nunca é buscado, portanto pode referenciar um nome de host interno ou uma 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 | Apenas 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 todos os matchers preenchidos. Pelo menos um entre `subject_prefix`, `claims` ou `condition` deve ser definido; um bloco `match` que contém apenas `audience` (ou nenhum matcher) é rejeitado. Isso protege contra regras que aceitariam todos os tokens de um emissor. | Matcher | Tipo | Semântica | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `subject_prefix` | string | Correspondência exata com a claim `sub` do JWT. Um `*` no final a torna uma correspondência de prefixo (o valor de `sub` deve começar com os caracteres antes do `*`). Diferencia maiúsculas de minúsculas. | | `audience` | string | A claim `aud` do JWT deve conter exatamente esta string. Quando `aud` é um array, qualquer elemento com correspondência exata satisfaz a verificação. | | `claims` | map\ | Cada chave é o nome de uma 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 ser avaliada 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 é avaliada como `true` para mais entradas do que o pretendido concede acesso mais amplo do que o pretendido. Prefira os matchers estáticos quando eles expressarem sua restrição. ## Erros ### Erros de troca de token `POST /v1/oauth/token` retorna erros no [formato padrão de erros da API](https://platform.claude.com/docs/pt-BR/api/errors). O SDK reporta 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 solicitaçã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 contêm. | Status | Erro | Causa | Resolução | | ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | `invalid_request_error` | `federation_rule_id` está malformado ou um campo obrigatório da solicitação está ausente. | Verifique o ID `fdrl_` e se o corpo da solicitação inclui todos os campos obrigatórios. | | 400 | `invalid_request_error` | `workspace_id` está presente, mas não é um ID `wrkspc_...` bem formado nem o literal `default`. | Corrija o valor de `workspace_id`; a mensagem de resposta indica 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 de chaves e cache](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` diferencia maiúsculas de minúsculas. `audience` exige 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 solicitaçã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 solicitação bruta) como o ID `wrkspc_...` ao qual você deseja restringir o token. Consulte [Solicitaçã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 solicitação não nomeia nenhum. Solicitaçõ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 reporta "no credentials" em vez de realizar a troca | Uma entre `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` ou `ANTHROPIC_IDENTITY_TOKEN[_FILE]` não está definida e nenhum perfil está ativo. | Defina as quatro variáveis ou configure um perfil. | | O SDK autentica com uma chave de API em vez de usar federação | `ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN` está definida e tem precedência. | Remova a definição da variável de chave ou token. | | `FileNotFoundError` na primeira solicitaçã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 do token projetado está montado e que o caminho corresponde. | | A troca de token é bem-sucedida, mas uma solicitação à Claude API retorna 403 | O escopo do token emitido 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 está exportada, mas definida como string vazia. Valores vazios podem ainda vencer sua posição de precedência. | Remova a definição da variável com `unset VAR` em vez de `VAR=""`. | ## Solucionar problemas de 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. As tentativas de troca recentes mostram 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 dispensa as verificações a seguir. Uma falha opaca comum é uma asserção reutilizada: uma asserção que contém uma claim `jti` só pode ser [trocada uma vez](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#jwt-verification), portanto uma carga de trabalho que reenvia o mesmo JWT (um loop de novas tentativas, 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 é emitir uma nova asserção para cada troca. Se você ainda precisar depurar a partir do próprio JWT, siga estas verificações em ordem: Decodifique a asserção que você enviou para poder comparar cada claim com a configuração do seu emissor e da sua 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 diferença em um único caractere faz a verificação falhar. A claim `aud` decodificada deve conter o valor `audience` da regra como correspondência exata. Quando `aud` é um array, um elemento deve corresponder exatamente. Compare `sub` com o `subject_prefix` da regra (diferencia maiúsculas de minúsculas; um `*` no 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 tiver se desviado, um token de outra forma válido é rejeitado. Para o modo `discovery`, busque `/.well-known/openid-configuration` via HTTPS público na porta 443 e confirme que `jwks_uri` é resolvido. Para `explicit_url`, busque a URL do JWKS diretamente. Para `inline`, confirme que a chave de assinatura do emissor não foi rotacionada desde que você registrou as chaves. Se o emissor rotacionou sua chave de assinatura e começou imediatamente a assinar com ela, as trocas podem falhar por até um minuto enquanto o cache de JWKS da Anthropic é atualizado. Consulte [Rotação de chaves e cache](https://platform.claude.com/docs/pt-BR/manage-claude/wif-reference#key-rotation-and-caching). ## Modos de origem do 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 as assinaturas de JWT desse emissor. Ele é 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 descoberta for diferente de `issuer_url`) | A Anthropic busca `/.well-known/openid-configuration`, lê `jwks_uri` do documento de descoberta e busca o JWKS a partir dali. | Seu IdP disponibiliza um documento de descoberta OIDC padrão na internet pública. A maioria dos provedores gerenciados (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) oferece suporte a 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 disponibiliza um documento de descoberta, ou a descoberta é apenas interna, 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 que o envolve). A Anthropic não faz nenhuma solicitaçã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 complementares mutuamente exclusivos por construção. Tanto `discovery` quanto `explicit_url` também aceitam uma string opcional `ca_cert_pem` para emissores que servem TLS a partir de uma CA privada. ### Rotação de chaves e cache Nos modos `discovery` e `explicit_url`, a Anthropic armazena em cache o JWKS buscado. Se o seu provedor de identidade publicar uma nova chave de assinatura e começar imediatamente a assinar tokens com ela, as trocas que apresentarem 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 o seu provedor de identidade começar a assinar tokens com ela, e mantenha a chave substituída no JWKS até que os tokens assinados por ela 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 descoberta OIDC do SPIRE ou um servidor de autorização personalizado do 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 o seu provedor de identidade rotacionar suas chaves de assinatura, você deve atualizar a configuração do emissor com o novo JWKS, caso contrário todas as trocas de token falharão na verificação de assinatura.