Аутентификация
Каждый запрос несёт ключ организации sk-org-…. Ключи выпускаются в консоли разработчика, раздел «Ключи API» (ключи API моделей ещё и ключом управления через /v1/keys), и различаются доступом, который вы выбираете в поле Доступ при выпуске. Ключей пять видов:
| Ключ | Зачем | access | Права | Что открывает | Кто платит |
|---|---|---|---|---|---|
| Ключ API моделей | Вызывает модели из вашего кода и тратит баланс организации | models | models:write | API моделей на api.samreshuuu.ru | Баланс организации |
| Ключ агента | Агент и интеграции организации из вашего кода | full | tools:write, chat:write | API агентов на samreshuuu.ru/v1, коннекторы по ключу и MCP-сервер на api.samreshuuu.ru с записью | Тариф организации |
| Ключ интеграций | Cursor и другие AI-приложения работают с интеграциями, без агента | apps | tools:write | Коннекторы по ключу и MCP-сервер с записью и repl_execute, без API агентов | Тариф организации |
| Ключ интеграций для чтения | AI-приложения читают интеграции и ничего не меняют | read | tools:read | Каталог, паспорта и читающие вызовы коннекторов по REST и через MCP | Тариф организации |
| Ключ управления | Выпускает и отзывает ключи API моделей через API, сам ничего не вызывает | management | keys:manage | /v1/keys на api.samreshuuu.ru, а также чтение /v1/key, /v1/credits и /v1/activity, см. Ключ управления | Ничего не тратит |
Вид ключа сервер выводит из доступа и возвращает полем kind: model_api у ключа API моделей, agent у ключа агента и обоих ключей интеграций, management у ключа управления. Ключ одного вида не открывает двери другого: ключ агента или интеграций на маршрутах 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». Создавать ключи могут владелец и администратор организации.
- Укажите название, например
Моя интеграция, или оставьте поле пустым: тогда ключ получит имя с датой выпуска. Поле Доступ открывается на Ключе API моделей; для API агентов выберите Ключ агента, для Cursor и других AI-приложений без агента Ключ интеграций, только для чтения Ключ интеграций для чтения. Под пунктом форма пишет, зачем этот ключ. Ключ API моделей описан на странице API моделей. - В поле Срок по умолчанию стоит 30 дней, каждый пункт называет дату конца. Без срока выпускает ключ, который работает до отзыва, и форма предупреждает об этом. Нажмите Создать ключ.
- Скопируйте ключ
sk-org-…и сохраните его: повторно увидеть полный секрет нельзя.
Если кнопки создания нет, обратитесь к владельцу или администратору организации.
Сохраните ключ в переменной окружения на своём сервере или компьютере:
Сначала проверьте ключ запросом списка агентов, с которыми можно говорить, без запуска агента:
При успешной авторизации вернётся JSON со списком агентов. Затем отправьте сообщение одному из них по хэндлу; этот запрос расходует квоту тарифа:
Ответ находится в choices[0].message.content. 401 означает, что ключ не принят, 403 означает, что у ключа нет chat:write, 404 означает, что model не называет доступного вам агента; остальные отказы описаны в разделе Ошибки и лимиты API агентов.
Контекст организации
Ключ привязан к организации, в которой выпущен, и к сотруднику, который его выпустил, и это доступ организации, а не личный. Ему доступны агенты, доступные этому сотруднику там, и общие подключения организации, открытые этому сотруднику. Памяти создателя, его личных подключений и его устройств ключ не видит: агент, отвечающий ключу, начинает без памяти, а подключение, которое видит только создатель, для ключа не подключено.
Ключ работает, только пока его создатель остаётся владельцем или администратором действующей организации. Это проверяется на каждом запросе: если создатель ушёл или удалён из организации, потерял роль или организация удалена, следующий запрос с ключом получит 401 AUTH_INVALID_CREDENTIALS.
Храните ключ на сервере, не в браузерной или мобильной сборке. Ключами управляют в консоли разработчика, раздел «Ключи API», или токеном вошедшего пользователя (ниже $ADMIN_TOKEN): выпуск и отзыв доступны владельцу и администратору, список видит любой участник.
Формат токенов
Ключи API имеют префикс sk-org-. Полный секрет показывается только один раз, при создании: сохраните его надёжно. Список ключей в консоли и в API показывает только маску key_masked (sk-org-…abcd, последние четыре знака ключа), никогда не секрет; у ключа, выпущенного до хранения хвоста, маска кончается многоточием после начала ключа. По префиксу 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 |
Какой ключ несёт какие права, сказано в таблице в начале страницы. API агентов открывает только Ключ агента. Ключ, выпущенный без access, получает доступ models, то есть это ключ API моделей.
Все права, которые знает сервер: tools:read, tools:write, chat:write, models:read, models:write, keys:manage. Права models:* и keys:manage принадлежат ключу API моделей и ключу управления и описаны на странице API моделей.
Управление ключами
Ключи выпускаются, переименовываются, перечисляются и отзываются в рамках организации. Все поля выпуска необязательны: без name ключ получает имя с датой выпуска, без access это ключ API моделей, без expires_in_days ключ работает, пока его не отзовут (срок допустим от 1 до 365 дней). Форма консоли сама предлагает 30 дней и шлёт этот срок.
Выпуск называет только access: models (ключ API моделей), full (ключ агента), apps (ключ интеграций), read (ключ интеграций для чтения) или management (ключ управления). Без access выпускается ключ API моделей, доступ вне этих пяти отклоняется с 422. PATCH меняет только то, что передано: name, лимит трат (spend_limit_kop и spend_limit_reset, "spend_limit_kop": null снимает лимит; лимит есть только у ключа API моделей, у остальных это 422 с кодом API_KEY_LIMIT_NOT_SPENDING) и disabled (true отключает ключ, false включает снова). Доступ и срок у выпущенного ключа не меняются: для другого доступа или срока выпустите новый ключ. Вид ключа выводит сервер и возвращает в поле kind; в теле выпуска kind не принимается.
Состояние ключа в ответе называет одно поле state. Если верны несколько, побеждает верхнее в таблице:
state | В консоли | Что значит | Что сделать |
|---|---|---|---|
revoked | Отозван | Ключ отозван навсегда. В списке виден только под отбором «Статус» → «Отозванные» | Ничего: выпустите новый ключ |
disabled | Отключён | Ключ выключили в консоли или ключом управления, все двери ему отказывают | Включить в меню строки или {"disabled": false} |
expired | Истёк | Срок прошёл, все двери ему отказывают | Выпустите новый ключ и отзовите этот |
limit_reached | Лимит исчерпан | Ключ API моделей потратил свой лимит, API моделей отказывает до начала нового периода, а у лимита без периода до его подъёма | Поднимите или снимите лимит (Изменить лимит) или дождитесь нового периода |
expiring | Скоро истечёт | Ключ работает, но срок скоро кончится | Выпустите новый ключ и замените им этот до конца срока |
active | Активен | Ключ работает | Переименовать, изменить лимит (у ключа API моделей), отключить или отозвать в меню строки |
Отзыв действует сразу, на HTTP и в MCP. Ключи сотрудника отзываются сами, когда он уходит или его удаляют из организации и когда он теряет роль владельца или администратора; все ключи организации отзываются при её удалении. Это касается и ключей API моделей, выпущенных его ключом управления: их держит тот же сотрудник. Неизвестный, отключённый, отозванный или истёкший ключ, а также ключ, создатель которого больше не может его держать (см. раздел «Контекст организации»), получает 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: ключ неизвестен, отключён, отозван или истёк либо его создатель больше не владелец и не администратор организации. Отключённый ключ достаточно включить в консоли, для остальных выпустите новый.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; ключ интеграций и ключ интеграций для чтения открывают коннекторы и MCP-сервер без агента.
В какой организации выполняется запрос?
В той, что выпустила ключ. Ключ является доступом организации, который выпустил один сотрудник: ему открыты общие подключения организации, но не память и не личные подключения создателя, и он работает, пока создатель остаётся там владельцем или администратором. Для работы в другой организации выпустите ключ там.
Что будет, если у ключа нет нужного права?
Запрос завершится ошибкой 403 AUTH_PERMISSION_DENIED, и текст ошибки назовёт недостающее право. У ключа агента chat:write открывает API агентов, tools:read открывает каталог, паспорта и чтение коннекторов по REST и через MCP, tools:write открывает вызовы на запись и repl_execute и включает tools:read. Права ключа API моделей перечислены на странице API моделей.
Какие права у ключа по умолчанию?
Без выбора доступа выпускается ключ API моделей (models:write): на нём же открывается поле «Доступ» формы «Новый ключ API» в консоли. Остальные ключи выпускаются с явным доступом: full (ключ агента), apps (ключ интеграций), read (ключ интеграций для чтения) или management (ключ управления).
Можно ли получить секрет ключа после его создания?
Нет. Полный секрет показывается только один раз, при создании. Список возвращает маску ключа key_masked (sk-org-…abcd), но не секрет. Форма консоли предлагает срок 30 дней, вариант «Без срока» есть; выпуск через API без expires_in_days даёт ключ без срока (см. «Управление ключами»).