使用 Admin API 管理 WIF

Admin API 允许您以编程方式创建和管理 Workload Identity Federation（工作负载身份联合）资源：服务账户、联合颁发者和联合规则。使用它可以将您的联合配置保存在基础设施即代码中，从 CI 进行配置，并在多个组织之间复现，而无需在 Claude Console 中逐步点击操作。这些端点与 Admin API 的其余部分共享 /v1/organizations 路径前缀。

前提条件

本页上的每个请求都使用携带 org:admin 作用域的 OAuth bearer token（持有者令牌）进行身份验证。该作用域仅授予具有 admin、owner 或 primary owner 角色的组织成员，并且它授予对整个组织的访问权限：任何工作区绑定都会被忽略。获取令牌有两种方式，它们携带不同的权限：来自您自己登录的令牌以用户身份操作，而联合令牌以服务账户身份操作，无法执行本页上的所有操作。

交互式（您的终端）

使用 ant CLI 在专用配置文件下登录，请求 org:admin 作用域（请参阅管理员访问），然后导出 bearer token。使用 --profile admin 登录会将 org:admin 凭据存储在其自己的配置文件名称下，并同时将其设为 CLI 的活动配置文件，而导出的变量适用于该 shell 中的每个 SDK 和 CLI 调用；因此请使用您专门保留用于管理的 shell，完成后取消设置该变量，并使用 ant profile activate default 将 CLI 切换回去：

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

交互式令牌是短期有效的；如果请求开始返回 401，请重新运行导出命令（它会自动刷新令牌）。

SDK 和 ant CLI 会自动读取 ANTHROPIC_AUTH_TOKEN；请在同一 shell 中保持 ANTHROPIC_API_KEY 未设置，因为这些端点拒绝 API 密钥，并且某些客户端在两者都设置时会优先使用密钥。

工作负载（CI 和自动化）

创建一条 oauth_scope: org:admin 的联合规则，其目标是 organization_role 为 admin 的服务账户。该规则本身必须在 Claude Console 中创建：授予工作负载组织管理员访问权限是一项经过深思熟虑的人工操作，而不是自动化可以为自身引导完成的事情。下一节将逐步介绍这一每个组织只需执行一次的设置。

引导工作负载以管理 WIF

一条在 Console 中创建的规则就足以将您其余的联合配置纳入基础设施即代码管理：向单个受信任的工作负载授予 org:admin 作用域，并让该工作负载通过此 API 管理联合颁发者和每条工作区作用域的联合规则。

1. 1

   在 Console 中创建 org:admin 规则

   在 Claude Console 中，前往 Settings → Workload identity 并选择 Connect workload，为您的自动化工作负载创建一条联合规则，例如您基础设施仓库中的 GitHub Actions 工作流。在 Advanced rule options 下，将规则的 OAuth 作用域设置为 org:admin：向导随后会创建具有 Admin 组织角色的新服务账户（或要求您选择一个现有的管理员服务账户作为目标）。

2. 2

   交换工作负载的身份令牌

   使用某个 SDK 或 ant CLI 的工作负载不会自行执行交换。使用联合环境变量将客户端指向该规则，并以无参数方式构造它，与构造 SDK 客户端中用于推理的方式完全相同；客户端在第一次请求时交换身份令牌，并在生成的访问令牌过期之前重新读取身份令牌并再次交换：

   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；
   # org:admin 端点会忽略该绑定。
   unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN       # both take precedence over federation

   

   ant CLI 读取相同的变量，或接受 --federation-rule、--organization-id、--service-account-id 和 --identity-token-file 标志。对于运行多个 ant 命令的工作负载，请使用联合配置文件而不是标志或环境变量：使用标志或变量时，CLI 会在每个进程中再次交换身份令牌，而携带 jti 声明的身份令牌（GitHub Actions 令牌即如此）只会被接受一次，因此第二个命令将被拒绝；当规则对所有工作区或多个工作区启用时，配置文件也是为 CLI 提供用于交换的 workspace_id 的唯一方式，因为与 SDK 不同，CLI 不会将 ANTHROPIC_WORKSPACE_ID 或 --workspace-id 传入交换。每个 SDK 也接受相同的设置作为显式构造函数参数，按语言分别展示于构造 SDK 客户端。有关完整列表和顺序，请参阅环境变量和凭据优先级。

   使用 curl 调用 API 的工作负载会自行将 JWT 交换为短期有效的 org:admin bearer token，使用与任何其他联合工作负载相同的令牌交换，并在 authorization: Bearer 标头中发送它。

3. 3

   通过 API 管理颁发者和工作区作用域的规则

   配置好客户端后（或者对于 curl，将铸造的令牌放入 ANTHROPIC_AUTH_TOKEN 后），工作负载使用本页上的端点创建和管理您的联合配置。

有关工作负载铸造的令牌可以和不可以执行的操作，请参阅权限和约束。如果您已经使用 Connect workload 向导创建了颁发者、服务账户或规则，请使用以下端点列出它们并将其导入您的基础设施即代码状态，而不是重新创建它们。

身份验证

所有端点都位于 https://api.anthropic.com/v1/organizations/ 下。对联合和服务账户端点的每个请求都需要 API 版本标头和 bearer token：

在 SDK 中，这些端点是 client.beta.organization.service_accounts、client.beta.organization.federation.issuers 和 client.beta.organization.federation.rules（在 CLI 中为 ant beta:organization:service-accounts、federation:issuers 和 federation:rules）。SDK 和 CLI 示例构造默认客户端，该客户端发送来自 ANTHROPIC_AUTH_TOKEN 的 bearer token，或者在自动化工作负载中，按照引导工作负载以管理 WIF中所述自行执行联合交换。SDK 列表方法按需获取更多页面，因此 limit 设置页面大小；PHP 和 Ruby 示例读取一页。

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}")

这些端点不接受 Admin API 密钥；Admin API 页面的 x-api-key 示例在此处不适用。

服务账户

服务账户（svac_...）是联合令牌所代表的非人类身份。将 organization_role 设置为 developer。

创建服务账户：

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}")

列出服务账户：

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}")

归档服务账户：

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}")

创建端点返回新的服务账户：

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

要读取或更新单个服务账户，请对 /v1/organizations/service_accounts/{service_account_id} 使用 GET 和 POST。服务账户必须是某个工作区的成员，联合令牌才能在其中操作。每个服务账户在您组织的默认工作区中都有隐式成员资格；使用对 /v1/organizations/service_accounts/{service_account_id}/workspaces 的 GET、POST 和 DELETE 为其他工作区添加显式成员资格，其中 DELETE 的目标是 .../workspaces/{workspace_id}。

有关完整的参数详情和响应模式，请参阅服务账户 API 参考。

联合颁发者

联合颁发者（fdis_...）向您的组织注册一个 OIDC 身份提供商。jwks 字段是一个可辨识联合类型，用于控制 Anthropic 如何获取提供商的签名密钥：

注册颁发者。此示例使用 JWKS 发现注册 GitHub Actions：

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}")

列出颁发者：

client = anthropic.Anthropic()

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

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

归档颁发者：

client = anthropic.Anthropic()

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

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

要读取或更新单个颁发者，请对 /v1/organizations/federation_issuers/{issuer_id} 使用 GET 和 POST。OAuth 调用方无法更新支撑某条 oauth_scope 不是 workspace:developer 或 workspace:inference 的规则的颁发者；请参阅权限和约束。

有关完整的参数详情和响应模式，请参阅联合颁发者 API 参考。

联合规则

联合规则（fdrl_...）将颁发者绑定到服务账户：来自该颁发者且满足规则匹配条件的 JWT 可以铸造以规则目标身份操作的令牌。创建请求中的 workspace_id 在创建时于该工作区中启用规则；之后可通过 /federation_rules/{rule_id}/workspaces 子资源添加更多工作区。创建时必须提供 workspace_id 或 applies_to_all_workspaces: true 之一。

创建规则。此示例允许来自 main 分支的 GitHub Actions 部署以该服务账户身份操作：

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}")

列出规则，可选择按颁发者筛选：

client = anthropic.Anthropic()

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

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

归档规则：

client = anthropic.Anthropic()

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

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

列表端点返回一页规则以及下一页的游标：

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

要读取或更新单条规则，请对 /v1/organizations/federation_rules/{rule_id} 使用 GET 和 POST。要管理规则可以在其中铸造令牌的工作区，请对 /v1/organizations/federation_rules/{rule_id}/workspaces 使用 GET 和 POST，并对 /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id} 使用 DELETE。

有关完整的参数详情和响应模式，请参阅联合规则 API 参考。

权限和约束

oauth_scope: org:admin 的规则必须以 organization_role 为 admin 的服务账户为目标。资源名称必须匹配 ^[a-z0-9-]+$，长度为 1 到 255 个字符，并且在组织内对每种资源类型唯一；有关完整的字段级约束，请参阅验证规则。

分页和归档

服务账户、联合颁发者和联合规则列表端点接受 limit（1 到 100，默认 20）和取自上一个响应的 page 游标。在下一个请求中将响应的 next_page 值作为 page 查询参数传递。规则工作区子资源列表返回完整集合，不分页。已归档的资源默认在列表中隐藏；传递 include_archived=true 以包含它们。

归档是软删除且是幂等的：归档已归档的资源会成功。当仍有活动的联合规则引用某个颁发者或服务账户时，归档它会返回 400；请先归档该规则。

另请参阅

• Workload Identity Federation：概念和 Console 设置演练
• WIF 参考：环境变量、验证规则、OAuth 作用域和错误代码
• Admin API：组织管理功能的其余部分
• Admin API 参考：为每个 Admin API 端点生成的请求和响应模式