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

Каждый запрос несёт ключ организации sk-org-…. Ключей три вида. Все выпускаются в консоли разработчика, раздел «Ключи API», и различаются доступом, который вы выбираете при выпуске:

КлючДоступ при выпускеЧто открываетКто платит
Ключ API моделейAPI моделей (models)API моделей на api.samreshuuu.ruБаланс организации
Ключ агентаПолный доступ (full), Только AI-приложения (apps) или Только просмотр (read)API агентов на samreshuuu.ru/v1, коннекторы по ключу и MCP-сервер на api.samreshuuu.ruТариф организации
Ключ управленияУправление ключами (management)Выпуск, лимит и отзыв ключей API моделей через /v1/keys на api.samreshuuu.ru; модели и агентов не вызываетНичего не тратит

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

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

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

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

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

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

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

bash
export SAMRESHUUU_API_KEY="sk-org-your_api_key"

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

bash
curl https://samreshuuu.ru/v1/models \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY"

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

python
import os from openai import OpenAI client = OpenAI(api_key=os.environ["SAMRESHUUU_API_KEY"], base_url="https://samreshuuu.ru/v1") reply = client.chat.completions.create( model="samreshu", messages=[{"role": "user", "content": "Привет! Что ты умеешь?"}], ) print(reply.choices[0].message.content)

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

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

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

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

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

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

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

Права ключа агента

Ключ несёт список прав (scope), минимум одно, каждое вида ресурс:действие. Запрос, которому нужно отсутствующее у ключа право, завершается ошибкой 403 AUTH_PERMISSION_DENIED, и текст ошибки называет это право.

ПравоЧто открывает
chat:writeAPI агентов: POST /v1/chat/completions и GET /v1/models
tools:readКоннекторы по ключу: каталог, паспорт, GET /v1/connections, статус согласия и читающие вызовы POST /v1/connectors/{service}/execute; в MCP list_services, describe_service и читающие вызовы connector_execute
tools:writeВызовы коннекторов на запись по REST и через MCP и любой repl_execute; включает tools:read

Варианты доступа ключа агента соответствуют наборам прав: Полный доступ (full) означает tools:write и chat:write, Только AI-приложения (apps) означает tools:write, Только просмотр (read) означает tools:read. API агентов открывает только Полный доступ. Ключ, выпущенный без access, получает доступ models, то есть это ключ API моделей.

Все права, которые знает сервер: tools:read, tools:write, chat:write, models:read, models:write, keys:manage. Права models:* и keys:manage принадлежат ключам консоли и описаны на странице API моделей.

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

Ключи выпускаются, переименовываются, перечисляются и отзываются в рамках организации. Все поля выпуска необязательны: без name ключ получает имя с датой выпуска, без access это ключ API моделей, без expires_in_days ключ работает, пока его не отзовут (срок допустим от 1 до 365 дней).

bash
# Создать ключ: полный секрет возвращается один раз curl -X POST https://samreshuuu.ru/api/v1/organizations/$ORG_ID/api-keys \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "production", "access": "full"}' # Переименовать ключ; лимит трат меняется тем же PATCH (spend_limit_kop) curl -X PATCH https://samreshuuu.ru/api/v1/organizations/$ORG_ID/api-keys/$KEY_ID \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "staging"}' # Список ключей без секрета: key_masked, kind, access, state, expires_at, last_used_at curl https://samreshuuu.ru/api/v1/organizations/$ORG_ID/api-keys \ -H "Authorization: Bearer $ADMIN_TOKEN" # Отозвать ключ (204) curl -X DELETE https://samreshuuu.ru/api/v1/organizations/$ORG_ID/api-keys/$KEY_ID \ -H "Authorization: Bearer $ADMIN_TOKEN"

Выпуск называет только access, вариант доступа: models (ключ API моделей), у ключа агента full (полный доступ), apps (только AI-приложения) или read (только просмотр), management (ключ управления). Без access выпускается ключ API моделей. PATCH меняет только то, что передано: name, лимит трат (spend_limit_kop и spend_limit_reset, "spend_limit_kop": null снимает лимит); доступ у выпущенного ключа не меняется, для другого доступа выпустите новый ключ. Вид ключа выводит сервер и возвращает в поле kind, у ключа агента это agent; в теле выпуска kind не принимается. Доступ, которого нет ни у одного вида, отклоняется с 422 и кодом API_KEY_ACCESS_OUTSIDE_KIND.

Состояние ключа в ответе называет одно поле state: active (работает), expiring (скоро истечёт), expired (истёк) или limit_reached (исчерпан лимит трат).

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

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

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

Минутный лимит ключа агента по тарифу, недельный лимит и отказ ключа без тарифа описаны в разделе Ошибки и лимиты API агентов.

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

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

Конверт ошибки, статусы и признак повтора описаны в разделе Ошибки и лимиты API агентов. Каждый 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 developer console, section API keys.»
  • AUTH_PERMISSION_DENIED: у ключа нет права, которое требует операция; текст его называет. Не повторяйте: выпустите ключ с этим правом.

API моделей отвечает в форме своего провода и своими кодами (missing_api_key, invalid_api_key, ambiguous_api_key, insufficient_scope), см. Ошибки API моделей.

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

Частые вопросы

Как аутентифицировать запрос?

Передайте ключ организации в заголовке Authorization: Bearer sk-org-... Все виды ключа выпускаются в консоли разработчика (https://platform.samreshuuu.ru), раздел «Ключи API», и различаются доступом. Ключ API моделей открывает API моделей на api.samreshuuu.ru, где ключ принимается и в заголовке x-api-key. Ключ агента открывает API агентов (/v1 на samreshuuu.ru), коннекторы по ключу и MCP-сервер на api.samreshuuu.ru.

В какой организации выполняется запрос?

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

Что будет, если у ключа нет нужного права?

Запрос завершится ошибкой 403 AUTH_PERMISSION_DENIED, и текст ошибки назовёт недостающее право. У ключа агента chat:write открывает API агентов, tools:read открывает каталог, паспорта и чтение коннекторов по REST и через MCP, tools:write открывает вызовы на запись и repl_execute и включает tools:read. Права ключа API моделей перечислены на странице API моделей.

Какие права у ключа по умолчанию?

Без выбора доступа выпускается ключ API моделей (models:write): так его выпускает кнопка «Создать ключ» в консоли. Ключ агента и ключ управления выпускаются с явным доступом: full, apps, read или management.

Можно ли получить секрет ключа после его создания?

Нет. Полный секрет показывается только один раз, при создании. Эндпоинты списка и отзыва возвращают лишь префикс ключа, но не секрет. Ключ работает, пока его не отзовут; срок задаёт необязательный expires_in_days (см. «Управление ключами»).

Была ли страница полезна?