Авторизация и аутентификация

Генерация токена в ЛК

Если вы хотите получать от API данные исключительно по свой учетной записи в Модульбанке, воспользуйтесь механизмом получения токена в Личном кабинете. Выберите пункт "Подключиться к API" в меню действий ЛК и следуйте дальнейшим инструкциям. Генерация токена в ЛК

После генерации токена вы можете сразу начать его использование для получения данных в API.

Важно! Сгенерированный в ЛК токен ничем не отличается от токена полученного по протоколу OAuth.


OAuth 2. Общая схема работы

Если вы разрабатываете приложение (бот для телеграма, плагин для общедоступной CRM и т.д.), которое может быть полезно для любого пользователя Модульбанка, вы можете авторизовывать пользователей через сервер авторизации Модульбанка по OAuth подобному протоколу. Схема авторизации пользователей идентична протоколу OAuth 2.0, за небольшим исключением что сервер авторизации Модульбанка кроме формата x-www-form-urlencoded также поддерживает формат json в теле запроса. Для того чтобы стороннее приложение могло совершать запросы к API от лица конкретного пользователя, приложению необходимо получить токен авторизации, подтверждающий что пользователь предоставил приложению права на выполнение тех или иных действий.

Важно! Если вы хотите авторизовывать пользователей Модульбанка по протоколу OAuth, ваше приложение должно быть зарегистрировано у нас. Для регистрации приложения напишите нам письмо на api@modulbank.ru. В ответ мы вышлем вам clientId и clientSecret - уникальные для каждого приложения идентификатор и секретное слово (необходимые параметры для взаимодействия с сервером авторизации Модульбанка).

Схема получения токена авторизации пользователя сторонним приложением. Схема авторизации пользователя

1) Пользователь инициирует авторизацию стороннего приложения
2) Приложение отправляет запрос Authorization Request на сервер авторизации Модульбанка
3) Сервер авторизации Модульбанка перенаправляет пользователя на страницу авторизации
4) Пользователь вводит свой логин и пароль, просматривает список запрашиваемых прав и подтверждает, либо отклоняет запрос авторизации.
5) Приложение получает ответ Authorization Response в виде HTTP Redirect со временным токеном для получения доступа или кодом ошибки.
6) Приложение, используя полученный временный токен доступа, отправляет запрос на получение токена авторизации
7) Ответ содержит токен авторизации (access_token)

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

Приложение отправляет запрос авторизации на сервер Модульбанка. Запрос авторизации отправляется из браузера клиента.

POST /v1/oauth/authorize HTTP/1.1
Host: api.modulbank.ru
Content-Type: application/json
Content-Length: <content-length>

Request body (в формате JSON):
{
    redirectUri: '<страница приложения на которую будет отправлен пользователь после авторизации>',
    clientId:'<ключ_приложения>',
    scope:'account-info operation-history assistant-service'
}

Параметры запроса:

Параметр Тип Описание
clientId string Идентификатор приложения. Для получения идентификатора для приложения напишите нам на api@modulbank.ru
responseType string code
redirectUri string URI, на который сервер OAuth передает результат авторизации. Значение этого параметра при посимвольном сравнении должно быть идентично значению redirect_uri, указанному при регистрации приложения. При сравнении не учитываются индивидуальные параметры приложения, которые могут быть добавлены в конец строки URI.
scope string Список запрашиваемых прав. Разделитель элементов списка - пробел. Элементы списка чувствительны к регистру.

По запросу авторизации пользователь перенаправляется на страницы OAuth авторизации Модульбанка. Пользователь вводит свой логин и пароль, просматривает список запрашиваемых прав, подтверждает либо отклоняет запрос авторизации приложения. Результат авторизации возвращается как HTTP 302 Redirect. Приложение должно обработать ответ HTTP Redirect. Можно получить только одну авторизацию для одного пользователя. Повторная авторизация (с тем же значением параметра clientId) аннулирует выданные ранее разрешения. Параметры перенаправления с результатом авторизации:

Параметр Тип Описание
code string Временный токен (authorization code), подлежащий обмену на постоянный токен авторизации. Присутствует если пользователь подтвердил авторизацию приложения
error string Код ошибки. Присутствует в случае ошибки или отказа в авторизации пользователем
description string Дополнительное текстовое пояснение ошибки

Возможные ошибки:

Значение поля error Описание
invalid_request В запросе отсутствуют обязательные параметры, либо параметры имеют некорректные или недопустимые значения.
invalid_scope Параметр scope отсутствует, либо имеет некорректное значение или имеет логические противоречия.
unauthorized_client Неверное значение параметра client_id, либо приложение заблокировано
access_denied Пользователь отклонил запрос авторизации приложения.

Пример ответа при успешной авторизации:

HTTP/1.1 302 Found
Location: https://your.app.com/?code=wovmrpbe0fgmskt

Ответ при отказе в авторизации:

HTTP/1.1 302 Found
Location:  https://your.app.com/?error=access_denied

Обмен временного токена на токен авторизации

Временный токен (значение поля code ответа) подлежит немедленному обмену на токен авторизации. Время действия этого токена — меньше 1 минуты. Приложение должно получить и обработать ответ сервера и немедленно самостоятельно обменять временный токен на токен авторизации. Если приложению не удалось получить ответ сервера, временный токен утерян, либо срок его действия истек, необходимо повторить процедуру авторизации. Если авторизация завершилась успехом, приложение должно немедленно обменять временный токен на токен авторизации. Для этого необходимо отправить запрос, содержащий временный токен, на сервер авторизации Модульбанка. Запрос должен быть отправлен методом POST.

Формат запроса:

POST /v1/oauth/token HTTP/1.1
Host: api.modulbank.ru
Content-Type: application/json
Content-Length: <content-length>

Request body (в формате JSON):
{
    "clientId":"<ключ_приложения>",
    "code":"z43qjxtwwxsvk4cl3vtmvo",
    "clientSecret":"секретный_ключ приложения",
    "redirectUri":"<URI, на который OAuth-сервер передает результат авторизации>",
}

Параметры запроса:

Параметр Тип Описание
code string Временный токен (authorization code)
clientId string Идентификатор приложения, полученный при регистрации
redirectUri string URI, на который OAuth-сервер передает результат авторизации. Значение этого параметра при посимвольном сравнении должно быть идентично значениюredirect_uri, ранее переданному в запросе authorize
clientSecret string Секретное слово для проверки подлинности приложения

В ответ на запрос сервер Модульбанка возвращает токен авторизации (accessToken), который является симметричным секретом приложения и дает право проводить операции со счетом пользователя. Токен возвращается в виде JSON-документа, который (в зависимости от результата обмена) может содержать одно из следующих полей:

Параметр Тип Описание
accessToken string Токен авторизации. Присутствует в случае успеха
error string Код ошибки. Присутствует в случае ошибки

Возможные ошибки:

Значение поля error Описание
invalid_request Обязательные параметры запроса отсутствуют или имеют некорректные или недопустимые значения
unauthorized_client Неверное значение параметра client_id или client_secret, либо приложение заблокировано
invalid_grant В выдаче access_token отказано. Временный токен не выдавался Модульбанком, либо просрочен, либо по этому временному токену уже выдан access_token (повторный запрос токена авторизации с тем же временным токеном)

Пример ответа при успешном обмене временного токена:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 293
Cache-Control: no-store

{
    "access_token":"aWQwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDA3MTQ5M2FhYy1lZTFjLTQ1ZWMtYTZkNC1kNTk4ZTQzM2NjNmY"
}

Пример ответа при ошибке:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 25
Cache-Control: no-store

{
    "error":"invalid_grant"
}

Использовать временный токен можно только один раз. Если приложению не удалось получить ответ сервера за время жизни временного токена, процедуру авторизации следует повторить сначала. Внимание! Полученный accessToken является симметричным секретом авторизации, поэтому разработчик приложения должен предпринять меры по его защите: хранить токен в зашифрованном виде, предоставлять доступ к нему только после авторизации пользователя в приложении. Срок действия токена 3 года. По истечении этого времени, токен автоматически аннулируется.

Отзыв токена

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

POST /v1/revoke HTTP/1.1
Host: api.modulbank.ru
Content-Type: application/json
Authorization: Bearer <токен который необходимо отозвать>

Пример успешного ответа:

HTTP/1.1 200 OK
Content-Length: 0

Права на выполнение операций

При запросе авторизации стороннее приложение должно явно указывать в параметре scope набор прав, необходимых приложению для работы.
Список возможных прав:

Название права Описание
account-info Получение информации о компаниях пользователя (один и тот же клиент Модульбанка может быть сотрудником нескольких компаний) и счетах компаний пользователя
operation-history Просмотр истории операций
operation-upload Загрузка операций в ЛК