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

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 укажите себя для персонального ключа или сервисный аккаунт для ключа, используемого несколькими пользователями. Вы также можете ограничить ключ определённым рабочим пространством, что позволит не указывать ID рабочего пространства вручную в последующих запросах.
• Использование ключа: Отправляйте его как 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 в 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 не ограничен рабочим пространством, вы должны указать ID рабочего пространства в заголовке 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": "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"
}

Значение заголовка, которое не является допустимым 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 в 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. Создайте сервисный аккаунт, если необходимо. Возможно, вам придётся попросить администратора организации создать его на странице 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), которому вы уже доверяете, таким как 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.

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

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