AdministraçãoAutenticação

Referência de WIF

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. Para tutoriais de configuração, consulte os guias de provedores.

Requisição de troca de token

POST /v1/oauth/token aceita um corpo JSON usando o grant jwt-bearer da RFC 7523. Os SDKs constroem essa requisição para você a partir das variáveis de ambiente; 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, ou o literal `default` para o workspace padrão da organização. Obrigatório quando a regra está habilitada para mais de um workspace. Quando omitido, o servidor seleciona o único workspace habilitado da regra.

Resposta da troca de token

POST /v1/oauth/token retorna uma resposta de token OAuth 2.0 padrão (RFC 6749 §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>`.
`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 no Claude Console em Settings > Organization.	`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 rotacionam em disco estejam sempre atualizados.	`/var/run/secrets/anthropic.com/token`

O caminho de federação via variáveis de ambiente diretas é ativado apenas 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 junto, mas não condiciona a ativação.

Uma variável definida como 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 prosseguir para a federação. Remova a definição de 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	Observações
1	Argumento do construtor (`api_key=`, `auth_token=`, `credentials=`)	Sempre sobrepõe todo o resto.
2	`ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN`	Oculta completamente a federação. Remova a definição dessas variáveis ao migrar de chaves de API.
3	`ANTHROPIC_PROFILE`	Carrega `<config_dir>/configs/<name>.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` + + .

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ê 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:

$ANTHROPIC_CONFIG_DIR
~/.config/anthropic no Linux e macOS
%APPDATA%\Anthropic no Windows

Perfil ativo

O nome do perfil ativo é resolvido nesta ordem:

$ANTHROPIC_PROFILE
O conteúdo de <config_dir>/active_config (um arquivo de uma linha escrito por ant profile activate <name>)
O nome literal default

O 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.

Layout de arquivos

Caminho	Conteúdo	Sensibilidade
`<config_dir>/configs/<profile>.json`	`version`, o bloco `authentication`, `organization_id`, `workspace_id` e `base_url`.	Não secreto. Seguro para commit ou para incluir em uma imagem.
`<config_dir>/credentials/<profile>.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 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

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 emitido pode chamar.

Escopo	Concede acesso a
`workspace:developer`	Todos os endpoints não administrativos da API do Claude no workspace da regra: Messages (incluindo streaming e contagem de tokens), Models, Managed Agents e suas sessões, Files e Skills. Isso corresponde ao acesso que uma chave de API emitida para o mesmo workspace tem.
`org:manage_tunnels`	A API de túneis MCP: listar e obter túneis, registrar e arquivar certificados de CA, revelar e rotacionar o token do túnel e arquivar túneis. O modal de criação de túnel do Console fixa esse escopo quando você cria uma regra a partir dele.

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.

Regras de validação

A Anthropic aplica essas restrições quando você cria ou atualiza emissores e regras, e ao verificar um JWT recebido no momento da troca.

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`	Opcional. O workspace (`wrkspc_...`) cuja cota, faturamento e limites de taxa se aplicam aos tokens emitidos sob essa regra. Deve ser um workspace na mesma organização, e a conta de serviço de destino deve ser membro desse workspace. Pode ser omitido para regras configuradas para apenas um workspace.
`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 requisição. Consulte Tempo de vida e atualização do token.

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 do 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 de 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 é acessado, portanto pode referenciar um hostname interno ou porta não padrão.

Verificação de JWT

Restrição	Detalhe
Tamanho máximo	O JWT em `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.
Tempo de vida máximo	O tempo de vida do token ( menos ) não deve exceder o máximo configurado do emissor (1 hora por padrão, configurável para cada emissor no Claude Console).

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 estar 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 torna-a uma correspondência de prefixo (o valor de `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 essa string exata. Quando `aud` é um array, qualquer elemento que corresponda exatamente satisfaz a verificação.
`claims`	map<string, string>	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.

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:

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 matchers estáticos quando eles expressarem sua restrição.

Erros

Erros de troca de token

POST /v1/oauth/token retorna erros no formato de erro padrão da API. O SDK encapsula falhas de troca em um FederationExchangeError tipado (ou equivalente na linguagem) que expõe o status HTTP, o corpo da resposta e o request_id.

Status	Erro	Causa	Resolução
400	`invalid_request`	`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`	`workspace_id_required`: a regra de federação está habilitada para mais de um workspace e a requisição omite `workspace_id`.	Defina `ANTHROPIC_WORKSPACE_ID` (ou o campo `workspace_id` no corpo de uma requisição bruta) com o ID `wrkspc_...` ao qual você quer que o token seja restrito. Consulte Requisição de troca de token.
400

Todas as falhas invalid_grant retornam HTTP 400; a causa específica é registrada apenas no lado do servidor e não é exposta na resposta.

Falhas comuns do lado do SDK

Sintoma	Causa	Resolução
O SDK reporta "no credentials" em vez de fazer 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 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á definida e vence na 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 lazy 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

Solucionar problemas de uma troca com falha

Uma resposta 400 invalid_grant é intencionalmente opaca; a causa específica é registrada apenas no lado do servidor.

Comece pela página de histórico de autenticação no Claude Console. Tentativas de troca recentes exibem 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.

Se você ainda precisar depurar a partir do próprio JWT, siga estas verificações em ordem:

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 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 diferir de `issuer_url`)	A Anthropic busca `<discovery_base or issuer_url>/.well-known/openid-configuration`, lê `jwks_uri` do documento de discovery e busca o JWKS a partir dele.	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 é usado apenas para comparação de string com a claim do JWT e nunca é acessado.

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 seu provedor de identidade publicar uma nova chave de assinatura e imediatamente começar a assinar tokens com ela, trocas que apresentam esses tokens podem falhar com erro de assinatura por até um 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 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 discovery OIDC SPIRE ou um servidor de autorização personalizado do Okta com 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.

Was this page helpful?

AdministraçãoAutenticação

Referência de WIF

Variáveis de ambiente, regras de validação, configuração de perfil e referência de erros para Workload Identity Federation.

Requisição de troca de token

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, ou o literal `default` para o workspace padrão da organização. Obrigatório quando a regra está habilitada para mais de um workspace. Quando omitido, o servidor seleciona o único workspace habilitado da regra.

Resposta da troca de token

POST /v1/oauth/token retorna uma resposta de token OAuth 2.0 padrão (RFC 6749 §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>`.
`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 no Claude Console em Settings > Organization.	`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 rotacionam em disco estejam sempre atualizados.	`/var/run/secrets/anthropic.com/token`

Precedência de credenciais

O SDK resolve credenciais nesta ordem. A primeira fonte que produz uma credencial vence.

Ordem	Fonte	Observações
1	Argumento do construtor (`api_key=`, `auth_token=`, `credentials=`)	Sempre sobrepõe todo o resto.
2	`ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN`	Oculta completamente a federação. Remova a definição dessas variáveis ao migrar de chaves de API.
3	`ANTHROPIC_PROFILE`	Carrega `<config_dir>/configs/<name>.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` + + .

Arquivo de configuração de perfil

Diretório de configuração

O SDK localiza o diretório de configuração nesta ordem:

$ANTHROPIC_CONFIG_DIR
~/.config/anthropic no Linux e macOS
%APPDATA%\Anthropic no Windows

Perfil ativo

O nome do perfil ativo é resolvido nesta ordem:

$ANTHROPIC_PROFILE
O conteúdo de <config_dir>/active_config (um arquivo de uma linha escrito por ant profile activate <name>)
O nome literal default

O 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.

Layout de arquivos

Caminho	Conteúdo	Sensibilidade
`<config_dir>/configs/<profile>.json`	`version`, o bloco `authentication`, `organization_id`, `workspace_id` e `base_url`.	Não secreto. Seguro para commit ou para incluir em uma imagem.
`<config_dir>/credentials/<profile>.json`	`version`, o `access_token` em cache, `expires_at` e (para login interativo) `refresh_token`.	Secreto. Escrito pelo SDK com modo `0600`.

Exemplo de perfil de federação

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 emitido pode chamar.

Escopo	Concede acesso a
`workspace:developer`	Todos os endpoints não administrativos da API do Claude no workspace da regra: Messages (incluindo streaming e contagem de tokens), Models, Managed Agents e suas sessões, Files e Skills. Isso corresponde ao acesso que uma chave de API emitida para o mesmo workspace tem.
`org:manage_tunnels`	A API de túneis MCP: listar e obter túneis, registrar e arquivar certificados de CA, revelar e rotacionar o token do túnel e arquivar túneis. O modal de criação de túnel do Console fixa esse escopo quando você cria uma regra a partir dele.

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.

Regras de validação

A Anthropic aplica essas restrições quando você cria ou atualiza emissores e regras, e ao verificar um JWT recebido no momento da troca.

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`	Opcional. O workspace (`wrkspc_...`) cuja cota, faturamento e limites de taxa se aplicam aos tokens emitidos sob essa regra. Deve ser um workspace na mesma organização, e a conta de serviço de destino deve ser membro desse workspace. Pode ser omitido para regras configuradas para apenas um workspace.
`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 requisição. Consulte Tempo de vida e atualização do token.

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 do 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).

Verificação de JWT

Restrição	Detalhe
Tamanho máximo	O JWT em `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.
Tempo de vida máximo	O tempo de vida do token ( menos ) não deve exceder o máximo configurado do emissor (1 hora por padrão, configurável para cada emissor no Claude Console).

Semântica de correspondência de regras

Matcher	Tipo	Semântica
`subject_prefix`	string	Correspondência exata com a claim `sub` do JWT. Um `` no final torna-a uma correspondência de prefixo (o valor de `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 essa string exata. Quando `aud` é um array, qualquer elemento que corresponda exatamente satisfaz a verificação.
`claims`	map<string, string>	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.

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:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

Erros

Erros de troca de token

Status	Erro	Causa	Resolução
400	`invalid_request`	`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`	`workspace_id_required`: a regra de federação está habilitada para mais de um workspace e a requisição omite `workspace_id`.	Defina `ANTHROPIC_WORKSPACE_ID` (ou o campo `workspace_id` no corpo de uma requisição bruta) com o ID `wrkspc_...` ao qual você quer que o token seja restrito. Consulte Requisição de troca de token.
400

Todas as falhas invalid_grant retornam HTTP 400; a causa específica é registrada apenas no lado do servidor e não é exposta na resposta.

Falhas comuns do lado do SDK

Sintoma	Causa	Resolução
O SDK reporta "no credentials" em vez de fazer 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 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á definida e vence na 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 lazy 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

Solucionar problemas de uma troca com falha

Uma resposta 400 invalid_grant é intencionalmente opaca; a causa específica é registrada apenas no lado do servidor.

Se você ainda precisar depurar a partir do próprio JWT, siga estas verificações em ordem:

Modos de origem do JWKS

`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 diferir de `issuer_url`)	A Anthropic busca `<discovery_base or issuer_url>/.well-known/openid-configuration`, lê `jwks_uri` do documento de discovery e busca o JWKS a partir dele.	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 é usado apenas para comparação de string com a claim do JWT e nunca é acessado.

Rotação de chaves e cache

Was this page helpful?