Инструкция по настройке авторизации через API v3

Для доступа к API Leader-ID с партнерского сайта предусмотрен механизм серверной авторизации на базе протокола OAuth 2.0.

Авторизация по протоколу OAuth включает следующие шаги:

1. Регистрация приложения: Вы должны зарегистрировать свое приложение обратившись в службу поддержки. Вы получите идентификатор клиента (client_id) и секретный ключ клиента (client_secret), которые будут использоваться для аутентификации вашего приложения.

2. Перенаправление пользователя: Ваше приложение должно перенаправить пользователя на страницу авторизации платформы — https://leader-id.ru/api/oauth/authorize.

3. Авторизация пользователя: Пользователь должен войти в свою учетную запись, после чего платформа OAuth создаст временный код авторизации.

4. Получение временного кода авторизации: Ваше приложение получает временный код авторизации, который можно использовать для получения токена доступа. Временный код будет передан обратно вашему приложению через параметр в URL-адресе перенаправления.

5. Обмен временного кода на токен доступа: Ваше приложение отправляет запрос на обмен временного кода авторизации на токен доступа, используя ваш идентификатор клиента (client_id), секретный ключ клиента (client_secret). Запрос проходит через сервер авторизации платформы OAuth.

6. Получение токена доступа: Если запрос на обмен временного кода верен и аутентификация проходит успешно, сервер авторизации выдаст вашему приложению токен доступа. Этот токен будет использоваться для вызова защищенных ресурсов на API-сервере.

7. Использование токена доступа: Ваше приложение может использовать полученный токен доступа для вызова API-сервера, предоставляемого платформой OAuth. Токен передается в параметре access_token, чтобы сервер мог проверить его валидность и разрешить доступ к запрашиваемым ресурсам.

Открытие диалога авторизации OAuth

Для начала процесса авторизации необходимо создать окно браузера и открыть в нем диалог авторизации с параметром response_type=code по адресу:

https://leader-id.ru/api/oauth/authorize?client_id=KEY&redirect_uri=REDIRECT_URI&response_type=code

KEY — идентификатор приложения, зарегистрированного заранее в сервисе Leader-ID.

REDIRECT_URI — адрес, на который будет передан code. Этот адрес должен находиться в пределах домена сайта, переданного службе поддержки Leader-ID.

Если пользователь не авторизован на сайте, то в диалоговом окне ему будет предложено ввести свой логин и пароль.

Получение временного кода авторизации (code)

После успешной авторизации, браузер пользователя будет перенаправлен по адресу REDIRECT_URI, который был указан при открытии диалога авторизации. При этом, код для получения ключа доступа (CODE) будет передан в GET-параметре на указанный адрес:

https://REDIRECT_URI?code=CODE

Код авторизации (code) может быть использован в течение 1 часа для получения access_token с вашего сервера.

В случае возникновения ошибки, браузер пользователя будет перенаправлен с указанием кода ошибки и описания ошибки. Пример возвращаемой ошибки:

{"message":"Validation error","code":1050,"errors":{"redirect_uri":"Адрес редиректа не совпадает с доменом"}}

Получение кода доступа (access_token)

Для получения access_token необходимо выполнить POST запрос с партнерского сайта к методу «Получить токен для доступа к API» с передачей параметра CODE и секретных данных приложения: KEY и SECRET. Секретный ключ SECRET никогда не должен содержаться в коде клиентского приложения.

https://leader-id.ru/api/oauth/access_token

Пример тела запроса:

{ 
"client_id": "KEY", 
"client_secret": "SECRET", 
"code": "CODE", 
"redirect_uri": "REDIRECT_URI", 
"grant_type": "authorization_code" 
}

Обратите внимание, что REDIRECT_URI должен быть тот же, что и в пункте 1.

В результате выполнения данного запроса ваш сервер получит вновь созданный access_token с ограниченным временем действия в одни сутки и refresh_token для обновления access_token. А также будет получен уникальный идентификатор пользователя user_id, который разрешил доступ.

Пример ответа сервера:

{ 
"access_token": "560c7________________", 
"expires_in": 1639138789, 
"refresh_token": "g33ff________________ ", 
"user_validated": true, 
"user_id":123456 
}

В случае ошибки будут переданы параметры error и error_description.

{"error":"unauthorized_client", "error_description":"Code is out of date!"} — используется неверный или устаревший код авторизации.

Обновление кода доступа (access_token)

Для обновления access_token с помощью refresh_token необходимо выполнить POST запрос с партнерского сайта к методу «Получить токен для доступа к API» с передачей параметра refresh_token.

https://leader-id.ru/api/oauth/access_token

Пример тела запроса:

{ 
"client_id": "KEY", 
"client_secret": "SECRET", 
"refresh_token": "REFRESH_TOKEN", 
"grant_type": "refresh_token" 
}

В результате выполнения данного запроса ваш сервер получит вновь созданный access_token с ограниченным временем действия в одни сутки и новый refresh_token для обновления.

Пример ответа сервера:

{ 
"access_token": "88659________________ ", 
"expires_in": 1638546410, 
"refresh_token": "g33ff________________ ", 
"user_id":123456 
}

Аутентификация по client_credentials

Для доступа к административным методам API, не требующим аутентификации пользователя, необходимо получить специальный ключ доступа access_token.

Для получения токена доступа необходимо выполнить POST запрос к методу «Получить токен для доступа к API», передав данные аутентификации приложения client_id и client_secret и параметр grant_type=client_credentials

https://leader-id.ru/api/oauth/access_token

Пример тела запроса:

{ 
"client_id": "KEY", 
"client_secret": "SECRET", 
"grant_type": "client_credentials"
}

Пример ответа сервера:

{ 
"access_token": "69371________________ ", 
"expires_in": 1379603097 
}

Обратите внимание, что при таком типе получения токена доступа сервер не возвращает refresh_token.