Управление WIF с помощью Admin API

Admin API позволяет программно создавать ресурсы Workload Identity Federation и управлять ими: сервисными аккаунтами, издателями федерации и правилами федерации. Используйте его, чтобы хранить конфигурацию федерации в виде «infrastructure as code» (инфраструктуры как кода), разворачивать её из CI и воспроизводить в разных организациях вместо того, чтобы настраивать всё вручную в Claude Console. Эти конечные точки используют общий префикс пути /v1/organizations с остальной частью Admin API.

Предварительные требования

Каждый запрос на этой странице аутентифицируется с помощью OAuth-токена носителя (bearer token), который несёт область действия (scope) org:admin. Эта область действия предоставляется только участникам организации с ролью admin, owner или primary owner и даёт доступ ко всей организации: любая привязка к рабочему пространству игнорируется. Получить токен можно двумя способами, и они несут разные разрешения: токен, полученный через ваш собственный вход, действует от имени пользователя, тогда как федеративный токен действует от имени сервисного аккаунта и не может выполнять все операции, описанные на этой странице.

Интерактивно (ваш терминал)

Войдите с помощью CLI ant под выделенным профилем, запросив область действия org:admin (см. Доступ администратора), затем экспортируйте токен носителя. Вход с --profile admin сохраняет учётные данные org:admin под собственным именем профиля и также делает его активным профилем CLI, а экспортированная переменная применяется к каждому вызову SDK и CLI в этой оболочке; поэтому используйте оболочку, которую вы выделяете для администрирования, сбросьте переменную, когда закончите, и переключите CLI обратно командой ant profile activate default:

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

Интерактивные токены недолговечны; если запросы начинают возвращать 401, повторно выполните команду экспорта (она автоматически обновляет токен).

SDK и CLI ant автоматически читают ANTHROPIC_AUTH_TOKEN; оставьте ANTHROPIC_API_KEY неустановленной в той же оболочке, поскольку эти конечные точки отклоняют ключи API, а некоторые клиенты предпочитают ключ, когда заданы обе переменные.

Рабочая нагрузка (CI и автоматизация)

Создайте правило федерации с oauth_scope: org:admin, нацеленное на сервисный аккаунт, у которого organization_role равна admin. Само правило должно быть создано в Claude Console: предоставление рабочей нагрузке доступа администратора организации — это осознанное действие человека, а не то, что автоматизация может настроить для себя сама. В следующем разделе описана эта однократная для каждой организации настройка.

Начальная настройка рабочей нагрузки для управления WIF

Одного правила, созданного в Console, достаточно, чтобы перевести остальную конфигурацию федерации под управление инфраструктурой как кодом: предоставьте одной доверенной рабочей нагрузке область действия org:admin и позвольте этой рабочей нагрузке управлять издателями федерации и всеми правилами федерации уровня рабочего пространства через этот API.

1. 1

   Создайте правило org:admin в Console

   В Claude Console перейдите в Settings → Workload identity и выберите Connect workload, чтобы создать одно правило федерации для вашей рабочей нагрузки автоматизации, например рабочего процесса GitHub Actions в вашем инфраструктурном репозитории. В разделе Advanced rule options установите OAuth-область действия правила в org:admin: мастер затем создаст новый сервисный аккаунт с ролью организации Admin (или попросит вас выбрать существующий сервисный аккаунт администратора в качестве цели).

2. 2

   Обменяйте токен идентичности рабочей нагрузки

   Рабочая нагрузка, использующая один из SDK или CLI ant, не выполняет обмен самостоятельно. Укажите клиенту правило с помощью переменных окружения федерации и создайте его без аргументов, точно так же, как для инференса в разделе Создание клиента 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

   

   CLI ant читает те же переменные или принимает флаги --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. Полный список и порядок см. в разделах Переменные окружения и Приоритет учётных данных.

   Рабочая нагрузка, вызывающая API с помощью curl, сама обменивает JWT на недолговечный токен носителя org:admin, используя тот же обмен токенов, что и любая другая федеративная рабочая нагрузка, и отправляет его в заголовке authorization: Bearer.

3. 3

   Управляйте издателями и правилами уровня рабочего пространства через API

   Когда клиент настроен (или, для curl, выпущенный токен находится в ANTHROPIC_AUTH_TOKEN), рабочая нагрузка создаёт вашу конфигурацию федерации и управляет ею с помощью конечных точек на этой странице.

О том, какие операции может и не может выполнять токен, выпущенный рабочей нагрузкой, см. Разрешения и ограничения. Если вы уже создали издателей, сервисные аккаунты или правила с помощью мастера Connect workload, получите их список с помощью следующих конечных точек и импортируйте их в состояние вашей инфраструктуры как кода вместо того, чтобы создавать заново.

Аутентификация

Все конечные точки находятся по адресу https://api.anthropic.com/v1/organizations/. Каждому запросу к конечным точкам федерации и сервисных аккаунтов нужны заголовок версии API и токен носителя:

В SDK эти конечные точки — client.beta.organization.service_accounts, client.beta.organization.federation.issuers и client.beta.organization.federation.rules (ant beta:organization:service-accounts, federation:issuers и federation:rules в CLI). Примеры SDK и CLI создают клиент по умолчанию, который отправляет токен носителя из ANTHROPIC_AUTH_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 не принимаются на этих конечных точках; примеры с x-api-key со страницы Admin API здесь не применимы.

Сервисные аккаунты

Сервисный аккаунт (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",
  "...": "..."
}

Чтобы прочитать или обновить отдельный сервисный аккаунт, используйте GET и POST на /v1/organizations/service_accounts/{service_account_id}. Сервисный аккаунт должен быть участником рабочего пространства, прежде чем федеративные токены смогут действовать в нём. Каждый сервисный аккаунт имеет неявное членство в рабочем пространстве по умолчанию вашей организации; добавляйте явные членства для других рабочих пространств с помощью GET, POST и DELETE на /v1/organizations/service_accounts/{service_account_id}/workspaces, где DELETE нацелен на .../workspaces/{workspace_id}.

Полные сведения о параметрах и схемы ответов см. в справочнике API сервисных аккаунтов.

Издатели федерации

Издатель федерации (fdis_...) регистрирует поставщика идентичности OIDC в вашей организации. Поле jwks — это размеченное объединение (discriminated union), которое управляет тем, как Anthropic получает ключи подписи поставщика:

Регистрация издателя. В этом примере регистрируется GitHub Actions с обнаружением 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}")

Список издателей:

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

Чтобы прочитать или обновить отдельного издателя, используйте GET и POST на /v1/organizations/federation_issuers/{issuer_id}. Вызывающая сторона с OAuth не может обновить издателя, на котором основано правило, чей oauth_scope отличается от workspace:developer или workspace:inference; см. Разрешения и ограничения.

Полные сведения о параметрах и схемы ответов см. в справочнике API издателей федерации.

Правила федерации

Правило федерации (fdrl_...) связывает издателя с сервисным аккаунтом: JWT от издателя, удовлетворяющие условиям сопоставления правила, могут выпускать токены, действующие от имени цели правила. workspace_id в запросе на создание включает правило в этом рабочем пространстве при создании; добавляйте другие рабочие пространства позже через подресурс /federation_rules/{rule_id}/workspaces. При создании требуется либо workspace_id, либо applies_to_all_workspaces: true.

Создание правила. Этот пример позволяет развёртываниям GitHub Actions из ветки main действовать от имени сервисного аккаунта:

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

Чтобы прочитать или обновить отдельное правило, используйте GET и POST на /v1/organizations/federation_rules/{rule_id}. Чтобы управлять рабочими пространствами, в которых правило может выпускать токены, используйте GET и POST на /v1/organizations/federation_rules/{rule_id}/workspaces и DELETE на /v1/organizations/federation_rules/{rule_id}/workspaces/{workspace_id}.

Полные сведения о параметрах и схемы ответов см. в справочнике 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