OAuth

Пункт «OAuth» доступен у приложений типов «Интеграция на сайте» и «Плагин». Здесь находятся данные OAuth-клиента, разрешённые адреса возврата и политики доступа. У готового решения этого пункта нет.

Владелец, администратор и разработчик приложения могут менять OAuth-настройки и работать с Client Secret. Наблюдатель видит Client ID и остальные настройки без возможности изменения; Client Secret ему не показывается.

Client ID и Client Secret

В блоке OAuth-ключей находятся:

• Client ID — публичный идентификатор приложения; перенесите его кнопкой копирования Client ID;
• Client Secret — секрет для аутентификации сервера приложения на token endpoint. Храните его только на сервере и не помещайте в браузерный код, логи или публичный репозиторий. Значение можно показать или скрыть и скопировать.

Регенерация Client Secret

Кнопка «Перегенерировать секрет» открывает окно подтверждения. Подтверждение выпускает новый Client Secret и сразу делает старый непригодным для обмена кода и обновления токенов. Отмена ничего не меняет.

Сохраните новое значение и замените секрет на сервере интеграции. Уже выпущенные access token продолжают работать до истечения срока или отзыва авторизации; регенерация секрета сама по себе их не отзывает.

Redirect URI

В разделе Redirect URIs нажмите «Добавить URI» и заполните адрес возврата. Ненужную строку можно удалить.

Адрес без протокола сохраняется с https://. Явный http:// разрешён только для loopback-адресов: localhost, его поддоменов, 127.x.x.x и ::1. Адрес с логином или паролем, фрагментом #... либо небезопасным протоколом отклоняется.

В запросе авторизации redirect_uri должен полностью совпадать с сохранённым значением. При обмене кода нужно снова передать тот же адрес. Значимы протокол, домен, порт, путь, query-параметры и завершающий слеш.

Два сценария доступа

У «Интеграции на сайте» в блоке «Сценарии OAuth-доступа» независимо настраиваются два сценария:

• вкладка «К проекту» открывает проектную политику. Авторизация относится к одному проекту, а API проверяет выданные в нём права;

• вкладка «От пользователя» открывает пользовательскую политику. Приложение действует от имени пользователя, но каждый вызов остаётся ограничен одновременно подтверждёнными разрешениями и актуальными правами пользователя на целевой ресурс.

Сценарий выбирается не при создании приложения, а в каждом запросе авторизации параметром subject. Для subject=project параметр project_id необязателен: если его нет, Senler AI предложит выбрать доступный проект. Для subject=user не передавайте project_id. Если subject отсутствует, используется project. Тип «Плагин» поддерживает только проектный сценарий.

Разрешения

Проектная и пользовательская политики имеют собственный набор разрешений. Для каждой доступны два режима:

• «Выбранные права» — если scope не передан, приложение запросит весь отмеченный набор. В scope можно передать его подмножество. Пользователь должен иметь возможность выдать каждое запрошенное право;
• «Доступные пользователю» — Senler AI исключит права, которых нет у авторизующегося пользователя. Передайте scope=project_access или scope=user_access для соответствующего сценария либо не передавайте scope.

Во втором режиме переключатель «Запросить все доступные права» определяет верхнюю границу. Когда он выключен, приложение получает пересечение отмеченных и доступных прав; когда включён — все разрешённые для этого OAuth-сценария права, которые пользователь может выдать. Точный набор всегда показывается перед подтверждением.

Для проектной авторизации can_view_projects добавляется обязательно и не снимается. Пользовательская авторизация может включать права проектов, приложений и аккаунта, но не разрешает управлять API-токенами, Client Secret или удалять приложения.

Сокращение политики сразу сужает действующие авторизации; пользовательская авторизация без оставшихся прав отзывается. Расширение политики не добавляет права в уже выданные токены — для новых прав пользователь проходит OAuth повторно. «Выбрать все» и «Снять все» меняют необязательные права.

Кнопка «Сохранить» применяет обе политики и Redirect URI.

Запрос авторизации

Откройте в браузере https://senler.io/oauth/authorize с параметрами:

• response_type=code — единственный поддерживаемый тип ответа;
• client_id — Client ID приложения;
• redirect_uri — точный зарегистрированный адрес;
• subject=project|user — сценарий доступа; без параметра используется project;
• project_id — необязательный заранее выбранный проект только для subject=project;
• scope — необязательный набор can_* в режиме выбранных прав либо project_access/user_access в динамическом режиме;
• state — случайное одноразовое значение, которое интеграция сохраняет до возврата пользователя.

Пример проектной авторизации с выбором проекта в Senler AI:

https://senler.io/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&subject=project&scope=project_access&state=RANDOM_STATE

Для пользовательского сценария замените subject=project на subject=user, используйте подходящий scope и не добавляйте project_id.

После подтверждения Senler AI возвращает code и исходный state на Redirect URI. При отказе возвращаются error=access_denied, error_description и state. Сервер интеграции обязан сравнить полученный state с сохранённым. Код действует 10 минут и используется только один раз.

Обмен кода на токены

Отправьте POST https://api.senler.io/api/apps/oauth/token в формате application/x-www-form-urlencoded или JSON. Client ID и Client Secret можно передать через HTTP Basic либо полями тела, но не двумя разными значениями одновременно.

curl -X POST https://api.senler.io/api/apps/oauth/token \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=AUTHORIZATION_CODE' \
  --data-urlencode 'redirect_uri=https://example.com/oauth/callback'

Ответ содержит access_token, refresh_token, token_type=Bearer, expires_in, scope и subject. Для subject=project также возвращается project_id, для subject=user — user_id. Используйте access_token как Authorization: Bearer ... и ориентируйтесь на expires_in, а не на предполагаемый срок действия.

Обновление токенов

Для обновления отправьте на тот же endpoint grant_type=refresh_token и текущий refresh_token, снова аутентифицировав OAuth-клиент.

curl -X POST https://api.senler.io/api/apps/oauth/token \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=REFRESH_TOKEN'

После успешного запроса прежний refresh token отзывается, а ответ содержит новую пару токенов. Сохраните оба новых значения до следующего обновления.

Отзыв пользовательской авторизации

Чтобы отключить один внешний клиент или отозвать собственную пользовательскую авторизацию, откройте «Подключённые приложения» в настройках аккаунта. Отключение клиента прекращает доступ только для этого подключения; отзыв пользовательской авторизации отключает все связанные с ней клиенты. Регенерация Client Secret заменяет ключ OAuth-клиента, но не отзывает уже выданные пользовательские доступы.

Ошибки token endpoint

Token endpoint возвращает { "error": "...", "error_description": "..." }:

• invalid_request — обязательного параметра нет или параметры противоречат друг другу;
• invalid_client — Client ID или Client Secret неверен; HTTP-статус ответа — 401;
• invalid_grant — код или refresh token истёк, уже использован, отозван либо выпущен для другого клиента;
• unauthorized_client — тип приложения не поддерживает OAuth;
• unsupported_grant_type — передан неподдерживаемый grant_type.

При invalid_grant начните новую авторизацию, при invalid_client проверьте актуальный Client Secret, а остальные ошибки исправляйте по error_description. Не повторяйте тот же запрос бесконечно.