Gerenciar WIF com a Admin API

A Admin API permite que você crie e gerencie recursos de Workload Identity Federation programaticamente: contas de serviço, emissores de federação e regras de federação. Use-a para manter sua configuração de federação em "infrastructure as code" (infraestrutura como código), provisioná-la a partir de CI e reproduzi-la entre organizações em vez de clicar pelo Claude Console. Esses endpoints compartilham o prefixo de caminho /v1/organizations com o restante da Admin API.

Pré-requisitos

Toda requisição nesta página se autentica com um token bearer OAuth que carrega o escopo org:admin. O escopo é concedido apenas a membros da organização com a função admin, owner ou primary owner, e concede acesso à organização inteira: qualquer vínculo de workspace é ignorado. Há duas maneiras de obter um token, e elas carregam permissões diferentes: um token do seu próprio login age como um usuário, enquanto um token federado age como uma conta de serviço e não pode executar todas as operações desta página.

Interativo (seu terminal)

Faça login com a CLI ant sob um perfil dedicado, solicitando o escopo org:admin (consulte Acesso de administrador), e então exporte o token bearer. Fazer login com --profile admin armazena a credencial org:admin sob seu próprio nome de perfil e também a torna o perfil ativo da CLI, e a variável exportada se aplica a toda chamada de SDK e CLI naquele shell; portanto, use um shell que você reserve para administração, remova a variável quando terminar e volte a CLI com ant profile activate default:

ant auth login --profile admin --scope "org:admin"
export ANTHROPIC_AUTH_TOKEN=$(ant auth print-credentials --profile admin --access-token)

Tokens interativos têm vida curta; se as requisições começarem a retornar 401, execute novamente o comando de exportação (ele atualiza o token automaticamente).

Os SDKs e a CLI ant leem ANTHROPIC_AUTH_TOKEN automaticamente; deixe ANTHROPIC_API_KEY sem definir no mesmo shell, porque esses endpoints rejeitam chaves de API e alguns clientes preferem a chave quando ambas estão definidas.

Workload (CI e automação)

Crie uma regra de federação com oauth_scope: org:admin que tenha como alvo uma conta de serviço cujo organization_role seja admin. A regra em si deve ser criada no Claude Console: conceder a um workload acesso de administrador da organização é uma ação humana deliberada, não algo que a automação possa inicializar por si mesma. A próxima seção percorre essa configuração feita uma vez por organização.

Inicializar um workload para gerenciar WIF

Uma regra criada no Console é suficiente para colocar o restante da sua configuração de federação sob infraestrutura como código: conceda a um único workload confiável o escopo org:admin e deixe esse workload gerenciar emissores de federação e todas as regras de federação com escopo de workspace por meio desta API.

1. 1

   Crie a regra org:admin no Console

   No Claude Console, vá para Settings → Workload identity e selecione Connect workload para criar uma regra de federação para seu workload de automação, por exemplo um workflow do GitHub Actions no seu repositório de infraestrutura. Em Advanced rule options, defina o escopo OAuth da regra como org:admin: o assistente então cria a nova conta de serviço com a função de organização Admin (ou pede que você escolha uma conta de serviço admin existente como alvo).

2. 2

   Troque o token de identidade do workload

   Um workload que usa um dos SDKs ou a CLI ant não realiza a troca por si mesmo. Aponte o cliente para a regra com as variáveis de ambiente de federação e construa-o sem argumentos, exatamente como para inferência em Construir o cliente do SDK; o cliente troca o token de identidade na primeira requisição e, antes que o token de acesso resultante expire, relê o token de identidade e o troca novamente:

   export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...        # the org:admin rule from step 1
   export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
   export ANTHROPIC_SERVICE_ACCOUNT_ID=svac_...       # the rule's target service account
   export ANTHROPIC_IDENTITY_TOKEN_FILE=/path/to/jwt  # or ANTHROPIC_IDENTITY_TOKEN
   # ANTHROPIC_WORKSPACE_ID é obrigatório apenas se a regra estiver habilitada para todos os
   # workspaces ou mais de um; os endpoints org:admin ignoram a vinculação.
   unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN       # both take precedence over federation

   

   A CLI ant lê as mesmas variáveis, ou aceita as flags --federation-rule, --organization-id, --service-account-id e --identity-token-file. Para um workload que executa mais de um comando ant, use um perfil de federação em vez de flags ou variáveis de ambiente: com flags ou variáveis, a CLI troca o token de identidade novamente em cada processo, e tokens de identidade que carregam uma claim jti (tokens do GitHub Actions carregam) são aceitos apenas uma vez, então um segundo comando seria rejeitado; um perfil também é a única maneira de fornecer à CLI um workspace_id para a troca quando a regra está habilitada para todos os workspaces ou para mais de um, porque, diferentemente dos SDKs, a CLI não passa ANTHROPIC_WORKSPACE_ID ou --workspace-id para a troca. Todo SDK também aceita as mesmas configurações como argumentos explícitos do construtor, mostrados por linguagem em Construir o cliente do SDK. Consulte Variáveis de ambiente e Precedência de credenciais para a lista completa e a ordenação.

   Um workload que chama a API com curl troca ele mesmo o JWT por um token bearer org:admin de vida curta, usando a mesma troca de token que qualquer outro workload federado, e o envia no cabeçalho authorization: Bearer.

3. 3

   Gerencie emissores e regras com escopo de workspace por meio da API

   Com o cliente configurado (ou, para curl, o token emitido em ANTHROPIC_AUTH_TOKEN), o workload cria e gerencia sua configuração de federação usando os endpoints desta página.

Para as operações que um token emitido por workload pode e não pode executar, consulte Permissões e restrições. Se você já criou emissores, contas de serviço ou regras com o assistente Connect workload, liste-os com os endpoints a seguir e importe-os para o estado da sua infraestrutura como código em vez de recriá-los.

Autenticação

Todos os endpoints ficam sob https://api.anthropic.com/v1/organizations/. Toda requisição aos endpoints de federação e de contas de serviço precisa do cabeçalho de versão da API e do token bearer:

Nos SDKs, esses endpoints são client.beta.organization.service_accounts, client.beta.organization.federation.issuers e client.beta.organization.federation.rules (ant beta:organization:service-accounts, federation:issuers e federation:rules na CLI). Os exemplos de SDK e CLI constroem o cliente padrão, que envia o token bearer de ANTHROPIC_AUTH_TOKEN ou, em um workload automatizado, realiza a troca de federação por si mesmo, conforme descrito em Inicializar um workload para gerenciar WIF. Os métodos de listagem dos SDKs buscam páginas adicionais sob demanda, então limit define o tamanho da página; os exemplos em PHP e Ruby leem uma página.

client = anthropic.Anthropic()

service_accounts = client.beta.organization.service_accounts.list()

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

Chaves de Admin API não são aceitas nesses endpoints; os exemplos com x-api-key da página da Admin API não se aplicam aqui.

Contas de serviço

Uma conta de serviço (svac_...) é a identidade não humana como a qual um token federado age. Defina organization_role como developer.

Crie uma conta de serviço:

client = anthropic.Anthropic()

service_account = client.beta.organization.service_accounts.create(
    name="inference-worker", organization_role="developer"
)

print(f"id: {service_account.id}")
print(f"name: {service_account.name}")

Liste contas de serviço:

client = anthropic.Anthropic()

service_accounts = client.beta.organization.service_accounts.list(limit=20)

for service_account in service_accounts:
    print(f"{service_account.id}: {service_account.name}")

Arquive uma conta de serviço:

client = anthropic.Anthropic()

service_account = client.beta.organization.service_accounts.archive(
    "svac_01ABCDEFabcdef0123456789XY"
)

print(f"id: {service_account.id}")
print(f"archived_at: {service_account.archived_at}")

O endpoint de criação retorna a nova conta de serviço:

{
  "id": "svac_...",
  "name": "inference-worker",
  "organization_role": "developer",
  "created_at": "...",
  "type": "service_account",
  "...": "..."
}

Para ler ou atualizar uma única conta de serviço, use GET e POST em /v1/organizations/service_accounts/{service_account_id}. Uma conta de serviço deve ser membro de um workspace antes que tokens federados possam agir nele. Toda conta de serviço tem uma associação implícita ao workspace padrão da sua organização; adicione associações explícitas a outros workspaces com GET, POST e DELETE em /v1/organizations/service_accounts/{service_account_id}/workspaces, onde DELETE tem como alvo .../workspaces/{workspace_id}.

Para detalhes completos de parâmetros e esquemas de resposta, consulte a referência da API de contas de serviço.

Emissores de federação

Um emissor de federação (fdis_...) registra um provedor de identidade OIDC na sua organização. O campo jwks é uma união discriminada que controla como a Anthropic busca as chaves de assinatura do provedor:

Registre um emissor. Este exemplo registra o GitHub Actions com descoberta de JWKS:

client = anthropic.Anthropic()

issuer = client.beta.organization.federation.issuers.create(
    name="github-actions",
    issuer_url="https://token.actions.githubusercontent.com",
    jwks={"type": "discovery"},
)

print(f"id: {issuer.id}")
print(f"name: {issuer.name}")
print(f"issuer_url: {issuer.issuer_url}")

Liste emissores:

client = anthropic.Anthropic()

issuers = client.beta.organization.federation.issuers.list(limit=20)

for issuer in issuers:
    print(f"{issuer.id}: {issuer.name}")

Arquive um emissor:

client = anthropic.Anthropic()

issuer = client.beta.organization.federation.issuers.archive(
    "fdis_01ABCDEFabcdef0123456789XY"
)

print(f"id: {issuer.id}")
print(f"archived_at: {issuer.archived_at}")

Para ler ou atualizar um único emissor, use GET e POST em /v1/organizations/federation_issuers/{issuer_id}. Um chamador OAuth não pode atualizar um emissor que sustenta uma regra cujo oauth_scope seja qualquer coisa diferente de workspace:developer ou workspace:inference; consulte Permissões e restrições.

Para detalhes completos de parâmetros e esquemas de resposta, consulte a referência da API de emissores de federação.

Regras de federação

Uma regra de federação (fdrl_...) vincula um emissor a uma conta de serviço: JWTs do emissor que satisfazem as condições de correspondência da regra podem emitir tokens que agem como o alvo da regra. O workspace_id na requisição de criação habilita a regra naquele workspace no momento da criação; adicione mais workspaces depois por meio do sub-recurso /federation_rules/{rule_id}/workspaces. É obrigatório informar workspace_id ou applies_to_all_workspaces: true na criação.

Crie uma regra. Este exemplo permite que deploys do GitHub Actions a partir do branch main ajam como a conta de serviço:

client = anthropic.Anthropic()

rule = client.beta.organization.federation.rules.create(
    name="gha-deploy",
    issuer_id="fdis_01ABCDEFabcdef0123456789XY",
    match={
        "subject_prefix": "repo:my-org/my-repo:ref:refs/heads/main",
        "claims": {"repository_owner": "my-org"},
    },
    target={
        "type": "service_account",
        "service_account_id": "svac_01ABCDEFabcdef0123456789XY",
    },
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    oauth_scope="workspace:developer",
    token_lifetime_seconds=600,
)

print(f"id: {rule.id}")
print(f"name: {rule.name}")

Liste regras, opcionalmente filtradas por emissor:

client = anthropic.Anthropic()

rules = client.beta.organization.federation.rules.list(
    issuer_id="fdis_01ABCDEFabcdef0123456789XY"
)

for rule in rules:
    print(f"{rule.id}: {rule.name}")

Arquive uma regra:

client = anthropic.Anthropic()

rule = client.beta.organization.federation.rules.archive(
    "fdrl_01ABCDEFabcdef0123456789XY"
)

print(f"id: {rule.id}")
print(f"archived_at: {rule.archived_at}")

O endpoint de listagem retorna uma página de regras e o cursor para a próxima página:

{
  "data": [{ "id": "fdrl_...", "name": "gha-deploy", "...": "..." }],
  "next_page": "..."
}

Para ler ou atualizar uma única regra, use GET e POST em /v1/organizations/federation_rules/{rule_id}. Para gerenciar os workspaces nos quais uma regra pode emitir tokens, use GET e POST em /v1/organizations/federation_rules/{rule_id}/workspaces, e DELETE em /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}.

Para detalhes completos de parâmetros e esquemas de resposta, consulte a referência da API de regras de federação.

Permissões e restrições

Uma regra com oauth_scope: org:admin deve ter como alvo uma conta de serviço cujo organization_role seja admin. Nomes de recursos devem corresponder a ^[a-z0-9-]+$, ter de 1 a 255 caracteres e ser únicos dentro de uma organização para cada tipo de recurso; para as restrições completas em nível de campo, consulte Regras de validação.

Paginação e arquivamento

Os endpoints de listagem de contas de serviço, emissores de federação e regras de federação aceitam limit (1 a 100, padrão 20) e um cursor page obtido da resposta anterior. Passe o valor next_page da resposta como o parâmetro de consulta page na próxima requisição. A listagem do sub-recurso de workspaces da regra retorna o conjunto completo sem paginação. Recursos arquivados ficam ocultos das listagens por padrão; passe include_archived=true para incluí-los.

O arquivamento é uma exclusão lógica e é idempotente: arquivar um recurso já arquivado é bem-sucedido. Arquivar um emissor ou uma conta de serviço retorna 400 enquanto uma regra de federação ativa ainda o referencia; arquive a regra primeiro.

Veja também

• Workload Identity Federation: conceitos e o passo a passo de configuração no Console
• Referência de WIF: variáveis de ambiente, regras de validação, escopos OAuth e códigos de erro
• Admin API: o restante da superfície de gerenciamento da organização
• Referência da Admin API: esquemas de requisição e resposta gerados para cada endpoint da Admin API