OAuth интеграции. Документация для разработчиков
Связанные статьи:
Что нужно сделать для запуска интеграции по OAuth:
- Заключить партнерское соглашение и получить client_id
- Сгенерировать secret с помощью API /v3/partner-applications/{applicationId}/reset-secret
- Определить список требуемых разрешений для работы приложения (доступ к мероприятия, файлам и тд)
- Реализовать запрос доступа с помощью OAuth и интегрироваться с UserAPI
- Провести финальный тест и добавить приложение в магазин интеграция МТС Линк
1. Получение client_id
После заключения партнерского приложения разработчик получает:
Параметр | Описание | Пример |
client_id | Строка. Код партнера | myapp324234234234 |
application_id | Число. Код приложения | 1 |
2. Создание secret
Чтобы получить secret нужно будет вызвать метод UserAPI (Получение secret для интеграции по OAuth):
curl --location --request POST 'https://userapi.mts-link.ru/v3/partner-applications/{applicationId}/reset-secret' \
--header 'x-auth-token: {apiKey}'
где
{ applicationId } - 1
{apiKey} - ключ к UserAPI вашего тестового стенда
Ответ:
{
"data": {
"secret": "{secret}"
}
}
3. Настройка тестового стенда
По умолчанию, все OAuth интеграции запрещены, чтобы предотвратить несанкционированный доступ. Администратору нужно явным образом разрешить интеграцию, тогда её смогут использовать другие сотрудники организации.
Разрешить доступ можно через API.
curl --location 'https://userapi.mts-link.ru/v3/partner-application-clients/enable' \
--header 'x-auth-token: {apiKey}' \
--header 'Content-Type: application/json' \
--data '{
"applicationId": 1
}'
Подробнее:
- Включение партнёрского приложения по API
- Отключение партнёрского приложения по API
- Список партнерских приложений
4. Разрешения на запуск методов
Необходимо запрашивать минимально необходимый список прав. Например, для выгрузки списка события достаточно доступа userapi_events_read. Ниже подробно перечислены доступы для вызова каждого метода UserAPI.
4.1 Мероприятия
4.1.1 Просмотр мероприятий userapi_events_read
- Список таймзон GET /timezones
- Данные мероприятия GET /userapi/eventsessions/{eventsessionId}
- Расписание мероприятий сотрудника GET /userapi/users/{userId}/events/schedule
- Участники мероприятия GET /userapi/eventsessions/{eventsessionId}/participations
- Файлы мероприятия GET /userapi/eventsessions/{eventSessionId}/files
- Файлы серии (шаблона) мероприятий GET /userapi/events/{eventId}/files
4.1.2 Создание и редактирование мероприятий userapi_events_write
- Список таймзон GET /timezones
- Создание шаблона (серии) мероприятия POST /userapi/events
- Создание мероприятия POST /userapi/events/{eventId}/sessions
- Регистрация на мероприятие POST /userapi/eventsessions/{eventsessionId}/register
- Приглашение на мероприятие POST /userapi/eventsessions/{eventsessionId}/invite
- Регистрация на серию мероприятий POST /userapi/events/{eventId}/register
- Приглашение на серию мероприятий POST /userapi/events/{eventId}/invite
- Прикрепить файл к шаблону (серии) мероприятий POST /userapi/events/{eventId}/files
- Прикрепить файл к мероприятию POST /userapi/eventsessions/{eventsessionId}/files
- Редактирование шаблона (серии) мероприятий PUT /userapi/organization/events/{eventId}
- Редактирование мероприятия PUT /userapi/eventsessions/{eventsessionId}
- Разрешение на просмотр онлайн записи мероприятия PUT /userapi/eventsessions/{eventsessionId}/records
- Открепить файл от мероприятия DELETE /userapi/eventsessions/{eventsessionId}/files/{fileId}
- Удаление шаблона (серии) мероприятий DELETE /userapi/organization/events/{eventId}
- Открепить файл от шаблона (серии) мероприятий DELETE /userapi/events/{eventId}/files/{fileId}
- Удаление мероприятия DELETE /userapi/eventsessions/{eventsessionId}
4.2 Файлы
4.2.1 Чтение файлов
Список файлов в файловой системе GET /userapi/fileSystem/files
Получение данных файла GET /userapi/fileSystem/file/{fileId}
4.2.2 Создание, изменение, удаление файлов userapi_files_write
Добавление файла в файловую систему POST /userapi/fileSystem/file
Удаление файла из файловой системы DELETE /userapi/fileSystem/file/{fileId}
5. Сценарий запроса токена
5.1 Авторизация пользователя
Размещаете в вашем приложении кнопку "Подключить МТС Линк". При нажатии пользователя нужно перенаправить на страницу запроса доступа к данным пользователя.
Формат ссылки: https://my.mts-link.ru/authorize?response_type=code
&client_id={clientId из шага 1}
&scope=userapi_events_read+userapi_events_write
&state={не обязательно, значение, которое вернем при обратном редиректе}
Опционально можно передать &redirect_uri=https://example-app.com/callback. Данный параметр указывает на какой url в этот раз отправить обратно, если зарегистрируете у нас более одного приложения.
После авторизации пользователя в МТС Линк и подтверждения им предоставления прав пользователь будет перенаправлен на указанный redirect_url с добавлением параметров code и state (если они его передавали).
?code={code}&state=123
Возможные ошибки:
Тариф клиента не разрешает интеграцию по API
Приложение не разрешено для установки в данной организации
Приложение не найдено
5.2 Получение JWT-токена
Ваше приложение с использованием полученного code выполняет запрос для получения JWT-токена
curl --location 'https://my.mts-link.ru/api/idp/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={clientId}' \
--data-urlencode 'client_secret={secret}' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code={code}'
Пример ответа
{
"token_type": "Bearer",
"expires_in": 600,
"access_token": "...",
"refresh_token": "..."
}
5.3 Выполнение запросов к UserAPI от имени пользователя
Некоторые методы UserAPI поддерживают работу одновременно с разными типами ключей, но отличаются заголовки. Оба типа авторизации в API продолжат работать дальше.
для OAuth параметр: --header 'authorization: Bearer {access_token}'
для обычного API ключа: --header 'x-auth-token: {apiKey}'
Пример запроса временных зон:
curl --location --request POST 'https://userapi.mts-link.ru/v3/timezones' \ --header 'authorization: Bearer {access_token}'
где {access_token} - полученное в предыдущем пункте значение.
5.4 Актуализация токена
curl --location 'https://my.mts-link.ru/api/idp/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={clientId}' \
--data-urlencode 'client_secret={secret}' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token={refresh_token}'
6. Управление токенами пользователей
Внутри личного кабинета МТС Линк пользователь видит список подключенных интеграций и может их удалить. При этом токен становится неактивным, все доступы приложения удаляются.
Администратор организации видит сессии пользователей и может при необходимости удалять сессии других пользователей, или запрещать приложение с одновременным удалением сессий сразу для всех пользователей организации.