Подключение по OAuth

Сначала получите ключи клиента и зарегистрируйте Redirect URI, затем задайте разрешения. Client Secret храните только на сервере.

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

Откройте в браузере 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. Не повторяйте тот же запрос бесконечно.