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

Claude API поддерживает три способа аутентификации запросов:

Ключи API и Workload Identity Federation предоставляют одинаковый доступ к эндпоинтам Claude API. Выберите ключи API, чтобы быстро начать работу: персональный ключ для вашей собственной разработки или ключ сервисного аккаунта для всего, что используется совместно. Переходите на Workload Identity Federation, когда у вашей рабочей нагрузки уже есть выданное платформой удостоверение, которое вы можете федерировать. Используйте App Attest для приложений iOS и macOS, которые вы распространяете среди конечных пользователей.

Ключи API

Ключи API — это статические секреты, которые вы генерируете в Claude Console и отправляете с каждым запросом как bearer-токен в заголовке Authorization.

Типы ключей

При создании ключа вы выбираете его тип, который определяет, что ключ может делать, где он работает и когда он перестаёт работать:

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

Используйте персональный ключ для вашей собственной разработки и скриптов. Общий персональный ключ действует как один человек и ломается, когда он уходит. Для общих или автоматизированных рабочих нагрузок (CI, производственные сервисы) попросите администратора организации создать сервисный аккаунт, чтобы у рабочей нагрузки было собственное удостоверение.

Ключи API рабочих пространств по-прежнему работают, но их следует считать устаревшими; предпочтительны ключи, привязанные к удостоверению, или Workload Identity Federation. Для миграции см. Замена ключей API рабочих пространств.

Создание и использование ключа

• Создание ключа: В Claude Console перейдите на страницу API keys (platform.claude.com/settings/keys) и нажмите Create key. Задайте имя ключа и выберите срок действия. Установите в поле Linked account себя для персонального ключа или сервисный аккаунт для ключа, используемого несколькими пользователями. Вы также можете ограничить ключ определённым рабочим пространством, что позволит не указывать идентификатор рабочего пространства вручную в будущих запросах.
• Использование ключа: Отправляйте его как Authorization: Bearer <key> в прямых HTTP-запросах или задайте переменную окружения ANTHROPIC_API_KEY, и клиентский SDK подхватит его автоматически.

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

Устаревший заголовок x-api-key: YOUR_API_KEY по-прежнему поддерживается вместо Authorization.

Храните ключи API в менеджере секретов, периодически меняйте их и отключайте или удаляйте любой ключ, который, по вашему мнению, мог утечь. На странице API keys в Claude Console действие Disable обратимо (Admin API сообщает status ключа как "inactive", а Re-enable возвращает его в "active"), тогда как Delete необратимо: ключ архивируется и по-прежнему отображается в List API Keys со значением status: "archived". Ключи с истёкшим сроком действия можно только удалить. Вы также можете задать срок действия при создании ключа, чтобы ограничить время, в течение которого утёкшие учётные данные остаются пригодными к использованию.

client = Anthropic(api_key="my-anthropic-api-key")
# или, с ANTHROPIC_API_KEY, установленным в окружении:
client = Anthropic()

Выбор рабочего пространства

Ключи API, созданные для определённого рабочего пространства, работают только в этом рабочем пространстве, и запросы API, использующие эти ключи, могут опускать ID рабочего пространства.

Если ваш ключ API не ограничен рабочим пространством, необходимо указывать идентификатор рабочего пространства в заголовке anthropic-workspace-id в каждом запросе. В следующем примере показано, как задать этот заголовок в запросе или в SDK.

Admin API принимает персональный ключ или ключ сервисного аккаунта только в том случае, если ключ не ограничен определённым рабочим пространством.

ID рабочего пространства можно найти в столбце ID на странице Workspaces (platform.claude.com/settings/workspaces) в Claude Console или вызвав эндпоинт List Workspaces. List Workspaces включает Default Workspace, только если передать include_default=true; его ID также содержится в заголовке ответа anthropic-workspace-id любого запроса, выполняемого в нём.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Обязателен в каждом запросе для ключа, не привязанного к рабочему пространству.
# Для ключа, привязанного к одному рабочему пространству, не указывайте extra_headers.
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)
print(message.content)

# Или задайте его один раз для каждого запроса от этого клиента:
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

Если запрос, сделанный с ключом, который не ограничен рабочим пространством, опускает заголовок, API возвращает 400 invalid_request_error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "This API key is not scoped to a workspace, so this request must include the anthropic-workspace-id header with the ID of the workspace to use. Add the header, or use an API key that is scoped to a workspace."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Значение заголовка, которое не является допустимым ID рабочего пространства, возвращает 400 invalid_request_error с сообщением anthropic-workspace-id header must be a valid workspace ID. Если рабочее пространство не существует или пользователь или сервисный аккаунт ключа не имеет к нему доступа, API возвращает 404 not_found_error с сообщением Workspace `<id>` not found., тот же ответ, что и для любого неизвестного рабочего пространства.

Workload Identity Federation выбирает рабочее пространство при обмене токенами; подробности см. в справочнике WIF.

Срок действия ключа

При создании ключа API на странице API keys в Claude Console вы выбираете срок действия: предустановленный (3 часа, 1 день, 7 дней или 30 дней), произвольную длительность или Never для ключей, которые вы храните в менеджере секретов и меняете самостоятельно. Если в вашей организации действует политика максимального срока действия, Console ограничивает предустановленные и произвольные значения максимумом политики, а вариант Never недоступен. Существующие ключи сохраняют своё текущее поведение; срок действия задаётся при создании и не может быть изменён впоследствии. Тот же выбор срока действия применяется при создании ключа Admin API в Claude Console.

Anthropic отправляет создателю ключа электронное письмо по мере приближения срока действия: за 7 дней до истечения для ключей, созданных со сроком жизни не менее 14 дней, и за 1 день для ключей со сроком жизни не менее 7 дней. Ключи с более коротким сроком жизни истекают без предупреждающего письма.

После истечения срока действия ключа запросы, сделанные с ним, возвращают 401 authentication_error. Создайте новый ключ для восстановления доступа; истёкшие ключи не могут быть повторно активированы.

Таблица ключей API в Console показывает срок действия каждого ключа, а Admin API сообщает временную метку expires_at каждого ключа в эндпоинтах List API Keys и Retrieve API Key, чтобы вы могли проверять и ротировать ключи до истечения их срока действия. Для ключей без срока действия это поле равно null.

Срок действия ограничивает время жизни скомпрометированных учётных данных, но он не заменяет гигиену секретов. Независимо от срока действия, храните ключи в менеджере секретов и отключайте или удаляйте любой ключ, который, как вы подозреваете, был скомпрометирован.

Замена ключей API рабочих пространств

Если у вас есть ключ рабочего пространства, вы можете захотеть заменить его на Workload Identity Federation или персональный ключ или ключ сервисного аккаунта. Это обеспечивает лучшую безопасность и наблюдаемость.

Подробности о настройке Workload Identity Federation, которая предпочтительнее долгоживущих ключей, см. в справочнике по WIF.

Чтобы заменить ключ рабочего пространства на персональный ключ или ключ сервисного аккаунта:

1. Определите тип ключа. Ваш собственный инструментарий должен использовать персональный ключ. Общая или автономная рабочая нагрузка должна использовать ключ сервисного аккаунта.
2. Создайте сервисный аккаунт, если необходимо. Возможно, вам придётся попросить администратора организации создать его на странице Service accounts (platform.claude.com/settings/service-accounts) в Claude Console и добавить его в соответствующее рабочее пространство.
3. Создайте новый ключ. Создайте его специально для рабочего пространства интеграции, если только интеграции не требуется несколько рабочих пространств.
4. Разверните новый ключ. Замените старый ключ везде, где интеграция его считывает, — обычно это переменная окружения ANTHROPIC_API_KEY или запись в менеджере секретов. Для ключа, не ограниченного рабочим пространством, также отправляйте заголовок anthropic-workspace-id, как показано в разделе Выбор рабочего пространства.
5. Удалите старый ключ. Убедитесь, что запросы выполняются успешно, затем удалите ключ рабочего пространства на странице ключей API в Claude Console.

Workload Identity Federation

Workload Identity Federation (WIF) позволяет рабочей нагрузке проходить аутентификацию с помощью кратковременного токена идентификации, выданного поставщиком удостоверений (IdP), которому вы уже доверяете. К таким IdP относятся AWS IAM, Google Cloud и любой совместимый со стандартами издатель OIDC (например, GitHub Actions, сервисные аккаунты Kubernetes, SPIFFE, Microsoft Entra ID или Okta). Рабочая нагрузка обменивает выданный IdP токен JWT через POST /v1/oauth/token на кратковременный токен доступа Claude API, а SDK автоматически обновляет этот токен до истечения его срока действия. Нет никакой строки sk-ant-api..., которую нужно создавать, распространять или менять.

Федерация убирает долгоживущие ключи Claude API из вашей среды, что ограничивает ущерб от утечки учётных данных и позволяет управлять доступом с помощью тех же средств контроля IdP, которые вы уже используете для облачных ресурсов. Однако сама по себе она не гарантирует сквозной безопасности: цепочка доверия надёжна лишь настолько, насколько надёжна конфигурация вашего поставщика удостоверений, и долгоживущий секрет на шаг раньше в этой цепочке (например, статические облачные учётные данные, с помощью которых можно получать токены IdP) всё равно может её подорвать. Сочетайте федерацию со средствами контроля вашего поставщика, такими как списки разрешённых IP-адресов, MFA и журналирование аудита.

Чтобы настроить федерацию, вы создаёте три ресурса в Claude Console (сервисный аккаунт, эмитент федерации и правило федерации), а затем указываете вашему SDK на это правило. См. Workload Identity Federation для полного пошагового руководства по настройке.

App Attest

App Attest аутентифицирует приложения для iOS и macOS, которые вызывают Claude API напрямую с устройства. Каждая установка доказывает, что она является подлинной, неизменённой сборкой приложения, зарегистрированного вами в Claude Console, с помощью сервиса Apple App Attest. Затем Anthropic выдаёт устройству кратковременный токен доступа, использование по которому оплачивается из вашего рабочего пространства. Токены ограничены вашим рабочим пространством, истекают через 1 час и разрешают только вызовы Messages API.

Чтобы зарегистрировать ваше приложение и получить client ID, см. App Attest для приложений iOS и macOS.

Следующие шаги