AdministraçãoAutenticação

Gerenciar WIF com a Admin API

Crie e gerencie contas de serviço, emissores e regras de Workload Identity Federation programaticamente para fluxos de trabalho de infraestrutura como código e CI.

A Admin API permite criar e gerenciar 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 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

Cada requisição nesta página é autenticada com um token OAuth bearer que carrega o escopo org:admin. O escopo é concedido apenas a membros da organização com a função de admin, owner ou primary owner, e concede acesso a toda a organização: qualquer vinculação de workspace é ignorada. Há duas maneiras de obter um token, e elas carregam permissões diferentes: um token do seu próprio login atua como um usuário, enquanto um token federado atua 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 usando um perfil dedicado, solicitando o escopo org:admin (consulte Acesso de admin), e então exporte o token bearer:

CLI

ant auth login --profile admin --scope "org:admin"
export ANTHROPIC_OAUTH_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).

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 admin da organização é uma ação humana deliberada, não algo que a automação possa inicializar por conta própria. A próxima seção percorre essa configuração que é feita uma única vez por organização.

Inicializar um workload para gerenciar WIF

Uma única 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.

Crie a regra org:admin no Console
No Claude Console, acesse 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).
Faça a regra corresponder a uma identidade de workload exata, não a um padrão amplo. subject_prefix é uma correspondência exata, a menos que termine em *. Para o GitHub Actions, fixe o subject a um branch protegido, como repo:my-org/my-repo:ref:refs/heads/main. Um curinga no final, como repo:my-org/my-repo:*, também corresponde a execuções de pull_request, incluindo execuções acionadas a partir de forks, de modo que qualquer pessoa que pudesse abrir um pull request no repositório poderia emitir um token org:admin. Consulte Restringir quais workflows podem se autenticar.
Troque o token de identidade do workload
Em tempo de execução, o workload troca o JWT do seu provedor de identidade por um token bearer org:admin de curta duração usando a mesma troca de token que qualquer outro workload federado.
Gerencie emissores e regras com escopo de workspace por meio da API
Com o token emitido em ANTHROPIC_OAUTH_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 estão sob https://api.anthropic.com/v1/organizations/. Cada requisição aos endpoints de federação e de conta de serviço precisa do cabeçalho de versão da API e do token bearer:

cURL

curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

Chaves da 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 atua. Defina organization_role como developer.

cURL

# Criar uma conta de serviço
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "inference-worker",
    "organization_role": "developer"
  }'

# Listar contas de serviço
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts?limit=20" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Arquivar uma conta de serviço
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/service_accounts/svac_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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 atuar nele. Toda conta de serviço tem uma associação implícita no workspace padrão da sua organização; adicione associações explícitas para outros workspaces com GET, POST e DELETE em /v1/organizations/service_accounts/{service_account_id}/workspaces, onde DELETE tem como alvo .../workspaces/{workspace_id}.

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 obtém as chaves de assinatura do provedor:

Valor de `jwks`	Quando usar
`{"type": "discovery"}`	O provedor serve `/.well-known/openid-configuration` na URL do emissor.
`{"type": "explicit_url", "url": "..."}`	Aponte diretamente para um endpoint JWKS.
`{"type": "inline", "keys": [...]}`	Faça upload do conjunto de chaves para provedores que não são acessíveis pela internet pública.

cURL

# Registrar um emissor (GitHub Actions, com descoberta de JWKS)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "github-actions",
    "issuer_url": "https://token.actions.githubusercontent.com",
    "jwks": {"type": "discovery"}
  }'

# Listar emissores
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers?limit=20" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Arquivar um emissor
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/federation_issuers/fdis_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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 dá suporte a uma regra cujo oauth_scope seja qualquer coisa diferente de workspace:developer ou workspace:inference; consulte Permissões e restrições.

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 atuam como o alvo da regra. O workspace_id na requisição de criação habilita a regra nesse workspace no momento da criação; adicione mais workspaces posteriormente por meio do sub-recurso /federation_rules/{rule_id}/workspaces. É obrigatório informar workspace_id ou applies_to_all_workspaces: true na criação.

cURL

# Criar uma regra (o GitHub Actions faz deploy a partir da branch main)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "gha-deploy",
    "issuer_id": "fdis_...",
    "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_..."
    },
    "workspace_id": "wrkspc_...",
    "oauth_scope": "workspace:developer",
    "token_lifetime_seconds": 600
  }'

# Listar regras, opcionalmente filtradas por emissor
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules?issuer_id=fdis_..." \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Arquivar uma regra
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/federation_rules/fdrl_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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

Permissões e restrições

Chamadores autenticados via OAuth só podem criar ou modificar regras cujo oauth_scope seja workspace:developer ou workspace:inference. Para criar ou modificar uma regra com qualquer outro escopo (como org:admin ou org:manage_tunnels), use o Console.
Um chamador OAuth não pode atualizar um emissor de federação que dá suporte a uma regra cujo oauth_scope seja qualquer coisa diferente de workspace:developer ou workspace:inference (como org:admin ou org:manage_tunnels). Considere registrar um emissor dedicado para a regra de bootstrap, para que os emissores por trás das regras com escopo de workspace permaneçam atualizáveis por meio da API.
Chaves da Admin API não são aceitas nesses endpoints, nem para leituras nem para escritas; use um token OAuth org:admin.

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 são ocultados das listagens por padrão; passe include_archived=true para incluí-los.

O arquivamento é uma exclusão lógica (soft delete) 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

Was this page helpful?

AdministraçãoAutenticação

Gerenciar WIF com a Admin API

Crie e gerencie contas de serviço, emissores e regras de Workload Identity Federation programaticamente para fluxos de trabalho de infraestrutura como código e CI.

Pré-requisitos

Interativo (seu terminal): Faça login com a CLI ant usando um perfil dedicado, solicitando o escopo org:admin (consulte Acesso de admin), e então exporte o token bearer:

CLI

ant auth login --profile admin --scope "org:admin"
export ANTHROPIC_OAUTH_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).

Inicializar um workload para gerenciar WIF

Crie a regra org:admin no Console
No Claude Console, acesse 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).
Faça a regra corresponder a uma identidade de workload exata, não a um padrão amplo. subject_prefix é uma correspondência exata, a menos que termine em *. Para o GitHub Actions, fixe o subject a um branch protegido, como repo:my-org/my-repo:ref:refs/heads/main. Um curinga no final, como repo:my-org/my-repo:*, também corresponde a execuções de pull_request, incluindo execuções acionadas a partir de forks, de modo que qualquer pessoa que pudesse abrir um pull request no repositório poderia emitir um token org:admin. Consulte Restringir quais workflows podem se autenticar.
Troque o token de identidade do workload
Em tempo de execução, o workload troca o JWT do seu provedor de identidade por um token bearer org:admin de curta duração usando a mesma troca de token que qualquer outro workload federado.
Gerencie emissores e regras com escopo de workspace por meio da API
Com o token emitido em ANTHROPIC_OAUTH_TOKEN, o workload cria e gerencia sua configuração de federação usando os endpoints desta página.

Autenticação

cURL

curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

Chaves da 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 atua. Defina organization_role como developer.

cURL

# Criar uma conta de serviço
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "inference-worker",
    "organization_role": "developer"
  }'

# Listar contas de serviço
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts?limit=20" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Arquivar uma conta de serviço
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/service_accounts/svac_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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",
  "...": "..."
}

Emissores de federação

Valor de `jwks`	Quando usar
`{"type": "discovery"}`	O provedor serve `/.well-known/openid-configuration` na URL do emissor.
`{"type": "explicit_url", "url": "..."}`	Aponte diretamente para um endpoint JWKS.
`{"type": "inline", "keys": [...]}`	Faça upload do conjunto de chaves para provedores que não são acessíveis pela internet pública.

cURL

# Registrar um emissor (GitHub Actions, com descoberta de JWKS)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "github-actions",
    "issuer_url": "https://token.actions.githubusercontent.com",
    "jwks": {"type": "discovery"}
  }'

# Listar emissores
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers?limit=20" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Arquivar um emissor
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/federation_issuers/fdis_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

Regras de federação

cURL

# Criar uma regra (o GitHub Actions faz deploy a partir da branch main)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "name": "gha-deploy",
    "issuer_id": "fdis_...",
    "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_..."
    },
    "workspace_id": "wrkspc_...",
    "oauth_scope": "workspace:developer",
    "token_lifetime_seconds": 600
  }'

# Listar regras, opcionalmente filtradas por emissor
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules?issuer_id=fdis_..." \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Arquivar uma regra
curl --fail-with-body -sS --request POST "https://api.anthropic.com/v1/organizations/federation_rules/fdrl_.../archive" \
  --header "anthropic-version: 2023-06-01" \
  --header "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

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": "..."
}

Permissões e restrições

Chamadores autenticados via OAuth só podem criar ou modificar regras cujo oauth_scope seja workspace:developer ou workspace:inference. Para criar ou modificar uma regra com qualquer outro escopo (como org:admin ou org:manage_tunnels), use o Console.
Um chamador OAuth não pode atualizar um emissor de federação que dá suporte a uma regra cujo oauth_scope seja qualquer coisa diferente de workspace:developer ou workspace:inference (como org:admin ou org:manage_tunnels). Considere registrar um emissor dedicado para a regra de bootstrap, para que os emissores por trás das regras com escopo de workspace permaneçam atualizáveis por meio da API.
Chaves da Admin API não são aceitas nesses endpoints, nem para leituras nem para escritas; use um token OAuth org:admin.

Paginação e arquivamento

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

Was this page helpful?

Pré-requisitos

Inicializar um workload para gerenciar WIF

Autenticação

Contas de serviço

Emissores de federação

Regras de federação

Permissões e restrições

Paginação e arquivamento

Veja também

Pré-requisitos

Inicializar um workload para gerenciar WIF

Autenticação

Contas de serviço

Emissores de federação

Regras de federação

Permissões e restrições

Paginação e arquivamento

Veja também

Pré-requisitos

Inicializar um workload para gerenciar WIF

Autenticação

Contas de serviço

Emissores de federação

Regras de federação

Permissões e restrições

Paginação e arquivamento

Veja também

Pré-requisitos

Inicializar um workload para gerenciar WIF

Autenticação

Contas de serviço

Emissores de federação

Regras de federação

Permissões e restrições

Paginação e arquivamento

Veja também