Аннотация

ЛитРес предоставляет возможность пользователям сторонних приложений* безопасно авторизоваться в них, используя аккаунт ЛитРес, с помощью протокола OAuth 2.0.

* – для удобства под приложениями будем подразумевать сайты, веб и мобильные приложения

Как пользоваться ЛитРес: OAuth

Шаг 1. Регистрация

Для регистрации в системе ЛитРес: OAuth необходимо:

1. подать заявку на участие в партнерской программе на странице https://www.litres.ru/partners/;

2. запросить доступ к сервису ЛитРес: OAuth по почте pam@litres.ru, указав в письме ваш партнерский id и следующие параметры:  

   Параметр	Пример значения	Описание
   s_title	Name	Название приложения в текстовом формате. Название будет отображаться в интерфейсе авторизации (см. пример).
   redirect_uri	https://name.ru	Callback URL или страница приложения, на которую будет перенаправлен пользователь после успешной авторизации в ЛитРес: ОAuth. Можно указать до 10 сallback url.

В случае успешного рассмотрения заявки, приложению будет присвоен client_id (идентификационный номер в системе ЛитРес: OAuth. Данный id, так же является id партнера - lfrom) и client_secret (секретный ключ).

Шаг 2. Получение токена

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

1. для авторизации в стороннем приложении через аккаунт ЛитРес, пользователь перенаправляется на специальный URL https://litres.ru/pages/oauth_authorize/, с принимаемыми GET-параметрами:
   • client_id – выдается приложению при регистрации;
   • response_type=code – для запроса кода авторизации; 
   • redirect_uri – Callback URL или страница приложения, на которую будет перенаправлен пользователь после успешной авторизации в ЛитРес: ОAuth. Если совпадение неточное, параметр игнорируется. Если параметр не указан, то редирект будет на Callback URI, указанный как главный при регистрации. 
   • state=STATE – строка состояния, возвращаемая без изменения. Этот параметр может быть использован для защиты от CSRF-атак или идентификации пользователя (максимальная допустимая длина строки – 1024 символа).

2. После успешной авторизации пользователя в аккаунте ЛитРес, у него запрашивается разрешение на доступ стороннего приложения к его данным.

   

   Если пользователь запрещает доступ, он перенаправляется по redirect_uri (указанный при регистрации) с параметрами:

   • state;
   • error = access_denied;
   • error_description = «Пользователь запретил доступ приложения к данным».

3. Если пользователь разрешает приложению доступ к своим данным ему выписывается одноразовый токен авторизации code (который будет действителен в течение 10 мин).

4. Далее он перенаправляется на redirect_uri (указанный при регистрации), с возвращаемыми GET-параметрами: state и code.
5. Одноразовый токен code обменивается на токен постоянного доступа прямым POST-запросом по URL https://litres.ru/oauth_token/ с параметрами: 
   
   • grant_type=authorization_code – параметр со статичным значением, передается именно в таком виде;
   • code;
   • client_id (выдается при регистрации);
   • client_secret (выдается при регистрации);

6. Если все параметры верны, то в ответ передается постоянный токен доступа: 

   {
     "access_token" : "e72186d21385cab3106f2066a67b40973b87e884",
     "expires_in" : 0,
     "token_type" : "bearer"
   }

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

   error_code	error_message	Описание
   11	ERROR_GRANT_TYPE_INVALID	Запрошен не grant_type=authorization_code, code отсутствует, ошибочен или просрочен.
   2	ERROR_CLIENT_SECRET	Не указан client_secret.

   Повторный вызов запроса с code вернет ошибку:

   {
     "error_description": "<описание ошибки>",
     "error_code": "<код ошибки>"
   }

7. Далее пользователь, используя постоянный токен доступа, может обращаться на сервер ЛитРес с разрешенными (при регистрации) данному приложению запросами.

   Дополнительную документацию к разрешенным типам запросов необходимо запрашивать отдельно по почте pam@litres.ru, указав в письме ваш партнерский id и параметр s_title (см. Шаг1).

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

   {
     "app": "1",
     "time": "2014-11-07T16:21:02+03:00",
     "sha": "b79d8e9993d20da6abe78838d3c7fbf640a4c52956569bef3c685d3453316b5c",
     "oauth_token": "7bad5f2fb752ee957a4ab74aaac7711g",
     "requests": [
             {
                   "func": "r_profile",
                   "id": "show_account_info",
                   "param": {
                     "fields": [
                       "money_details", "mail", "login", "first_name", "middle_name", "last_name", "nickname", "phone", "birth_date", "gender", "reviews_cnt", "quotes_cnt", "biblio", "socnet"
                     ]
                   }
             }
   }

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

   error_code	error_message	Описание
   101184	ERROR_USER_NOT_GIVE_PERMISSION	Пользователь не дал разрешения приложению на этот метод (приложение может перекинуть на запрос прав).
   101185	ERROR_OAUTH_TOKEN_INVALID	Токен не действителен.