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

Запросы интеграции проходят аутентификацию API-ключом организации (sk-org-…) в заголовке Authorization: Bearer. Ключ открывает две двери, каждую в пределах своих scope:

Ключ передаётся только в Authorization: Bearer; заголовок x-api-key не читается, и запрос только с ним получит 401 AUTH_HEADER_MISSING.

Нативный /api/v1 это внутренний API приложений Сам Решу: он принимает токен вошедшего пользователя, на ключ отвечает 401 AUTH_TOKEN_INVALID и контрактом для интеграций не является. Эндпоинты /v1 устроены наоборот: принимают только ключ, а на токен пользователя отвечают тем же кодом.

Создать ключ и отправить первый запрос

1. Войдите в Сам Решу и выберите нужную организацию.
2. Откройте Настройки → API-ключи и нажмите Создать ключ. Создавать ключи могут владелец и администратор организации.
3. Укажите название, например Моя интеграция. В поле Доступ оставьте Полный доступ: он выбран по умолчанию и включает chat:write. «Только AI-приложения» и «Только просмотр» открывают MCP, но не чат-эндпоинт.
4. Выберите срок действия и нажмите Создать ключ.
5. Скопируйте ключ sk-org-… и сохраните его: повторно увидеть полный секрет нельзя.

Если кнопки создания нет, обратитесь к владельцу или администратору организации.

Сохраните ключ в переменной окружения на своём сервере или компьютере:

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

При успешной авторизации вернётся JSON со списком агентов. Затем отправьте сообщение одному из них по хэндлу; этот запрос расходует доступную квоту:

Ответ находится в choices[0].message.content. 401 означает, что ключ не принят; 403 означает, что у ключа нет chat:write; 404 означает, что model не называет доступного вам агента. Примеры для Python и Node.js: OpenAI-совместимый API.

Контекст организации

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

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

Храните ключ на сервере, не в браузерной или мобильной сборке. Ключами управляют в Настройках → API-ключи или токеном вошедшего пользователя (ниже $ADMIN_TOKEN): выпуск и отзыв доступны владельцу и администратору, список видит любой участник.

Формат токенов

API-ключи имеют префикс sk-org-. Полный секрет показывается только один раз, при создании: сохраните его надёжно. Эндпоинты списка и отзыва возвращают только префикс ключа, никогда не секрет. По префиксу sk-org- утёкший ключ находит секрет-сканер: добавьте шаблон в pre-commit и поиск по логам.

Scopes

Ключ несёт список scope, минимум один: tools:read, tools:write, chat:write, sessions:read, sessions:write. Каждый имеет вид ресурс:действие. Запрос, которому нужен отсутствующий у ключа scope, завершается ошибкой 403 AUTH_PERMISSION_DENIED. Ключ, выпущенный через API без scopes, получает tools:write, chat:write, sessions:write; пустой список и любое другое слово (включая write:tools, chat, read:tools, admin) отклоняются с 422.

Доступ в настройках соответствует набору scope: Полный доступ означает tools:write, chat:write, sessions:write, тот же набор, что получает ключ, выпущенный через API без scopes; Только AI-приложения означает tools:write, Только просмотр означает tools:read. Чат-эндпоинт открывает только Полный доступ.

Управление ключами

Ключи выпускаются, перечисляются и отзываются в рамках организации. Каждый ключ истекает через expires_in_days: по умолчанию 90, допустимо от 1 до 365; явный null создаёт бессрочный ключ.

Отзыв действует сразу, на HTTP и в MCP. Ключи сотрудника отзываются сами, когда он покидает организацию или теряет роль владельца или администратора, а все ключи организации отзываются при её удалении. Неизвестный, отозванный или истёкший ключ, а также ключ, создатель которого больше не может его держать (см. раздел «Контекст организации»), получает 401 AUTH_INVALID_CREDENTIALS.

Ротация без простоя. Выпустите новый ключ, выкатите его, убедитесь по last_used_at, что старый больше не используется, и отзовите старый. Отметку ставят запросы к /v1/* и к MCP, но не чаще раза в 10 мин: ключ затих, когда его last_used_at старше этого окна и больше не сдвигается. Ключ, попавший в репозиторий, лог или чат, отзывайте сразу, даже если следов использования нет. Для разных сред (разработка, прод) держите разные ключи.

Лимиты частоты и вызовы из браузера

Частота запросов ограничена на каждый ключ, в минуту, по тарифу организации:

Превышение даёт 429 RATE_LIMIT_EXCEEDED с заголовком Retry-After в секундах. Расход модели считается отдельным недельным лимитом, см. Ошибки и лимиты.

Вызовы со страницы в браузере с чужого origin режет CORS: на кросс-доменные запросы с ключом API не отвечает. Ходите через свой сервер, тогда и ключ не попадёт на страницу.

Ошибки аутентификации

Отказ /v1 приходит в публичном объекте ошибки: ветвитесь по error.type и error.code, а не по тексту. Каждый 401 несёт заголовок WWW-Authenticate: Bearer realm="samreshuuu". Статус, код и признак повтора ниже берутся из реестра ошибок сервера; текст отказа по ключу приведён после таблицы.

• AUTH_HEADER_MISSING: нет заголовка Authorization. Добавьте Bearer.
• AUTH_TOKEN_INVALID: не Bearer, повреждённый токен или ключ организации на нативном /api/v1. Используйте /v1 или MCP.
• AUTH_TOKEN_EXPIRED: истёк токен пользователя. Ключи так не истекают: истёкший ключ получает AUTH_INVALID_CREDENTIALS.
• AUTH_INVALID_CREDENTIALS: ключ неизвестен, отозван или истёк либо его создатель больше не владелец и не администратор организации. Текст: «Invalid, revoked or expired API key. Create a new key in the organization settings.»
• AUTH_PERMISSION_DENIED: у ключа нет scope, который требует операция; текст его называет. Не повторяйте: выпустите ключ с этим scope.
• RATE_LIMIT_EXCEEDED: лимит запросов ключа. Подождите Retry-After секунд.

MCP отвечает на отказ входа до чтения MCP-сообщения: HTTP 401, тот же заголовок WWW-Authenticate и тело {"detail": {…}} (code, message, message_en); см. MCP. Тем же телом detail отвечает нативный /api/v1 (управление ключами).