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

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

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

Ключи API

«API keys» (ключи API) — это статические секреты, которые вы генерируете в Claude Console и отправляете с каждым запросом в заголовке x-api-key.

Типы ключей

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

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

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

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

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

• Создайте ключ: перейдите в Settings → API keys в Claude Console и нажмите Create key. Дайте ключу имя и выберите срок действия. Установите Linked account на себя для персонального ключа или на сервисный аккаунт для ключа, совместно используемого несколькими пользователями. Вы также можете ограничить ключ конкретным рабочим пространством, что позволит не указывать идентификатор рабочего пространства вручную в будущих запросах.
• Используйте ключ: установите заголовок x-api-key в прямых HTTP-запросах или задайте переменную окружения ANTHROPIC_API_KEY, и клиентские SDK подхватят её автоматически.

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

Храните ключи API в менеджере секретов, периодически ротируйте их и отключайте или удаляйте любой ключ, который, по вашему подозрению, мог утечь. На странице API keys действие 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 с такими ключами идентификатор рабочего пространства можно не указывать.

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

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

Идентификатор рабочего пространства можно найти в столбце ID раздела Settings → Workspaces в Claude Console или вызвав конечную точку List Workspaces. Ни один из этих способов не показывает идентификатор Default Workspace: прочитайте его из заголовка ответа anthropic-workspace-id любого запроса, выполняемого в нём (например, сделанного с ключом рабочего пространства из Default Workspace), или из scope.workspace_id такого ключа в List API Keys.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Обязательно в каждом запросе для ключа с несколькими рабочими пространствами.
# Опустите extra_headers для ключа с одним рабочим пространством.
message = client.messages.create(
    model="claude-opus-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": "anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Значение заголовка, не являющееся допустимым идентификатором рабочего пространства, возвращает ошибку 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, которая предпочтительнее долгоживущих ключей, см. в разделе Workload Identity Federation.

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

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

Workload Identity Federation

«Workload Identity Federation» (федерация удостоверений рабочих нагрузок), или WIF, позволяет рабочей нагрузке аутентифицироваться с помощью краткосрочного токена идентификации, выданного «identity provider» (поставщиком удостоверений), или 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, с помощью сервиса App Attest от Apple. Затем Anthropic выдаёт устройству краткосрочный токен доступа, использование по которому тарифицируется на ваше рабочее пространство. Токены ограничены вашим рабочим пространством, истекают через один час и разрешают только вызовы Messages API.

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

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