Аутентификация
Каждый запрос несёт ключ организации 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 устроены наоборот: принимают только ключ, а на токен пользователя отвечают тем же кодом.
Создать ключ агента и отправить первый запрос
- Войдите в Сам Решу и выберите нужную организацию.
- Откройте консоль разработчика, раздел «Ключи API», и нажмите Создать ключ. Создавать ключи могут владелец и администратор организации.
- Укажите название, например
Моя интеграция. В поле Доступ выберите вариант: Полный доступ (выбран по умолчанию) открывает API агентов и коннекторы с записью, Только AI-приложения открывает коннекторы и MCP с записью, но не API агентов, Только просмотр открывает каталог, паспорта и чтение коннекторов. Вариант API моделей выпускает ключ API моделей, а не ключ агента: он описан на странице API моделей. - Выберите срок действия и нажмите Создать ключ.
- Скопируйте ключ
sk-org-…и сохраните его: повторно увидеть полный секрет нельзя.
Если кнопки создания нет, обратитесь к владельцу или администратору организации.
Сохраните ключ в переменной окружения на своём сервере или компьютере:
Сначала проверьте ключ запросом списка агентов, с которыми можно говорить, без запуска агента:
При успешной авторизации вернётся JSON со списком агентов. Затем отправьте сообщение одному из них по хэндлу; этот запрос расходует квоту тарифа:
Ответ находится в 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:write | API агентов: 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 дней).
Выпуск называет только 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 (см. «Управление ключами»).