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

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



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

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

Интерактивный (ваш терминал): Войдите в систему с помощью CLI ant под отдельным профилем, запросив область действия org:admin (см. Административный доступ), затем экспортируйте bearer-токен:

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.

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



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

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

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 не принимаются на этих конечных точках; примеры с x-api-key со страницы Admin API здесь неприменимы.



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

Сервисный аккаунт (svac_...) — это нечеловеческая идентичность, от имени которой действует федеративный токен. Установите organization_role в значение developer.

# Создание сервисного аккаунта
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",
  "...": "..."
}

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



Эмитенты федерации

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

# Зарегистрировать издателя (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"

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



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

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

# Создать правило (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": "..."
}

Чтобы прочитать или обновить отдельное правило, используйте 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}.



Разрешения и ограничения

Правило с 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