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

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

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

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

Интерактивный способ (ваш терминал)

Войдите с помощью ant CLI под отдельным профилем, запросив область org:admin (см. Административный доступ), затем экспортируйте bearer-токен. Вход с --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 и ant CLI автоматически считывают 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 перейдите на страницу Workload identity (platform.claude.com/settings/workload-identity-federation) и выберите 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. Полный список и порядок приоритета см. в разделах Переменные окружения и Приоритет учётных данных.

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

3. 3

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

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

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

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

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

В SDK эти эндпоинты доступны как client.organization.service_accounts, client.organization.federation.issuers и client.organization.federation.rules (ant organization:service-accounts, federation:issuers и federation:rules в CLI). Примеры для SDK и CLI создают клиент по умолчанию, который отправляет bearer-токен из ANTHROPIC_AUTH_TOKEN или, в автоматизированной рабочей нагрузке, сам выполняет обмен федерации, как описано в разделе Начальная настройка рабочей нагрузки для управления WIF. Методы получения списков в SDK загружают последующие страницы по требованию, поэтому limit задаёт размер страницы; примеры на PHP и Ruby считывают одну страницу.

client = anthropic.Anthropic()

service_accounts = client.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.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.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.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 — это размеченное объединение, определяющее, как Anthropic получает ключи подписи поставщика:

Регистрация издателя. В этом примере регистрируется GitHub Actions с обнаружением JWKS:

client = anthropic.Anthropic()

issuer = client.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.organization.federation.issuers.list(limit=20)

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

Архивирование издателя:

client = anthropic.Anthropic()

issuer = client.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.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.organization.federation.rules.list(
    issuer_id="fdis_01ABCDEFabcdef0123456789XY"
)

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

Архивирование правила:

client = anthropic.Anthropic()

rule = client.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: сгенерированные схемы запросов и ответов для эндпоинтов сервисных аккаунтов и федерации