Управление 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "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" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "name": "inference-worker",
    "organization_role": "developer"
  }'

# Список сервисных аккаунтов
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/service_accounts?limit=20" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Архивирование сервисного аккаунта
curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/organizations/service_accounts/svac_.../archive" \
  -H "anthropic-version: 2023-06-01" \
  -H "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}.

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



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

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

# Регистрация издателя (GitHub Actions, с обнаружением JWKS)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_issuers" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "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" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Архивирование издателя
curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/organizations/federation_issuers/fdis_.../archive" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

Чтобы прочитать или обновить отдельного издателя, используйте 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)
curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/federation_rules" \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "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_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "authorization: Bearer $ANTHROPIC_OAUTH_TOKEN"

# Архивирование правила
curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/organizations/federation_rules/fdrl_.../archive" \
  -H "anthropic-version: 2023-06-01" \
  -H "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}.

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