管理身份验证

使用 Admin API 管理 WIF

以编程方式创建和管理 Workload Identity Federation 服务账户、颁发者和规则，用于基础设施即代码和 CI 工作流。

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

前提条件

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

交互式（您的终端）： 使用 ant CLI 在专用配置文件下登录，请求 org:admin 作用域（请参阅管理员访问权限），然后导出不记名令牌：

CLI

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

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

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

引导工作负载以管理 WIF

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

在 Console 中创建 org:admin 规则
在 Claude Console 中，转到 Settings → Workload identity 并选择 Connect workload，为您的自动化工作负载（例如基础设施仓库中的 GitHub Actions 工作流）创建一条联合规则。在 Advanced rule options 下，将规则的 OAuth 作用域设置为 org:admin：向导随后会创建具有 Admin 组织角色的新服务账户（或要求您选择一个现有的管理员服务账户作为目标）。
将规则匹配到一个确切的工作负载身份，而不是宽泛的模式。subject_prefix 是精确匹配，除非它以 * 结尾。对于 GitHub Actions，请将 subject 固定到受保护的分支，例如 repo:my-org/my-repo:ref:refs/heads/main。尾部通配符（如 repo:my-org/my-repo:*）也会匹配 pull_request 运行，包括从 fork 触发的运行，因此任何能够对该仓库发起拉取请求的人都可以生成 org:admin 令牌。请参阅限制哪些工作流可以进行身份验证。
交换工作负载的身份令牌
在运行时，工作负载使用与任何其他联合工作负载相同的令牌交换，将其身份提供商颁发的 JWT 交换为短期有效的 org:admin 不记名令牌。
通过 API 管理颁发者和工作区作用域的规则
将生成的令牌存入 ANTHROPIC_OAUTH_TOKEN 后，工作负载即可使用本页面上的端点创建和管理您的联合配置。

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

身份验证

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

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"

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

服务账户

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

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" \
  --header "content-type: application/json" \
  --data '{
    "name": "inference-worker",
    "organization_role": "developer"
  }'

# 列出服务账户
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"

# 归档服务账户
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"

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

{
  "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}。

联合颁发者

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

`jwks` 值	使用场景
`{"type": "discovery"}`	提供商在颁发者 URL 上提供 `/.well-known/openid-configuration`。
`{"type": "explicit_url", "url": "..."}`	直接指向 JWKS 端点。
`{"type": "inline", "keys": [...]}`	为无法从公共互联网访问的提供商上传密钥集。

cURL

# 注册签发者（GitHub Actions，使用 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"}
  }'

# 列出签发者
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"

# 归档签发者
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"

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

联合规则

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

cURL

# 创建规则（GitHub Actions 从 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
  }'

# 列出规则，可选择按颁发者筛选
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"

# 归档规则
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"

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

{
  "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。

权限和约束

通过 OAuth 身份验证的调用方只能创建或修改 oauth_scope 为 workspace:developer 或 workspace:inference 的规则。要创建或修改具有任何其他作用域（例如 org:admin 或 org:manage_tunnels）的规则，请使用 Console。
OAuth 调用方无法更新支撑 oauth_scope 不是 workspace:developer 或 workspace:inference（例如 org:admin 或 org:manage_tunnels）的规则的联合颁发者。建议为引导规则注册一个专用颁发者，以便工作区作用域规则背后的颁发者仍可通过 API 更新。
这些端点不接受 Admin API 密钥，无论是读取还是写入；请使用 org:admin OAuth 令牌。

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 端点生成的请求和响应架构

Was this page helpful?

管理身份验证

使用 Admin API 管理 WIF

以编程方式创建和管理 Workload Identity Federation 服务账户、颁发者和规则，用于基础设施即代码和 CI 工作流。

前提条件

交互式（您的终端）： 使用 ant CLI 在专用配置文件下登录，请求 org:admin 作用域（请参阅管理员访问权限），然后导出不记名令牌：

CLI

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

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

引导工作负载以管理 WIF

在 Console 中创建 org:admin 规则
在 Claude Console 中，转到 Settings → Workload identity 并选择 Connect workload，为您的自动化工作负载（例如基础设施仓库中的 GitHub Actions 工作流）创建一条联合规则。在 Advanced rule options 下，将规则的 OAuth 作用域设置为 org:admin：向导随后会创建具有 Admin 组织角色的新服务账户（或要求您选择一个现有的管理员服务账户作为目标）。
将规则匹配到一个确切的工作负载身份，而不是宽泛的模式。subject_prefix 是精确匹配，除非它以 * 结尾。对于 GitHub Actions，请将 subject 固定到受保护的分支，例如 repo:my-org/my-repo:ref:refs/heads/main。尾部通配符（如 repo:my-org/my-repo:*）也会匹配 pull_request 运行，包括从 fork 触发的运行，因此任何能够对该仓库发起拉取请求的人都可以生成 org:admin 令牌。请参阅限制哪些工作流可以进行身份验证。
交换工作负载的身份令牌
在运行时，工作负载使用与任何其他联合工作负载相同的令牌交换，将其身份提供商颁发的 JWT 交换为短期有效的 org:admin 不记名令牌。
通过 API 管理颁发者和工作区作用域的规则
将生成的令牌存入 ANTHROPIC_OAUTH_TOKEN 后，工作负载即可使用本页面上的端点创建和管理您的联合配置。

身份验证

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

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"

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

服务账户

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

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" \
  --header "content-type: application/json" \
  --data '{
    "name": "inference-worker",
    "organization_role": "developer"
  }'

# 列出服务账户
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"

# 归档服务账户
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"

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

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

联合颁发者

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

`jwks` 值	使用场景
`{"type": "discovery"}`	提供商在颁发者 URL 上提供 `/.well-known/openid-configuration`。
`{"type": "explicit_url", "url": "..."}`	直接指向 JWKS 端点。
`{"type": "inline", "keys": [...]}`	为无法从公共互联网访问的提供商上传密钥集。

cURL

# 注册签发者（GitHub Actions，使用 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"}
  }'

# 列出签发者
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"

# 归档签发者
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"

联合规则

cURL

# 创建规则（GitHub Actions 从 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
  }'

# 列出规则，可选择按颁发者筛选
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"

# 归档规则
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"

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

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

权限和约束

通过 OAuth 身份验证的调用方只能创建或修改 oauth_scope 为 workspace:developer 或 workspace:inference 的规则。要创建或修改具有任何其他作用域（例如 org:admin 或 org:manage_tunnels）的规则，请使用 Console。
OAuth 调用方无法更新支撑 oauth_scope 不是 workspace:developer 或 workspace:inference（例如 org:admin 或 org:manage_tunnels）的规则的联合颁发者。建议为引导规则注册一个专用颁发者，以便工作区作用域规则背后的颁发者仍可通过 API 更新。
这些端点不接受 Admin API 密钥，无论是读取还是写入；请使用 org:admin OAuth 令牌。

分页和归档

另请参阅

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

Was this page helpful?

前提条件

引导工作负载以管理 WIF

身份验证

服务账户

联合颁发者

联合规则

权限和约束

分页和归档

另请参阅

前提条件

引导工作负载以管理 WIF

身份验证

服务账户

联合颁发者

联合规则

权限和约束

分页和归档

另请参阅

前提条件

引导工作负载以管理 WIF

身份验证

服务账户

联合颁发者

联合规则

权限和约束

分页和归档

另请参阅

前提条件

引导工作负载以管理 WIF

身份验证

服务账户

联合颁发者

联合规则

权限和约束

分页和归档

另请参阅