Ввод кода на странице авторизации Яндекс OAuth

На некоторых устройствах (например, на телевизорах) вводить код подтверждения в приложении может быть неудобно. В этом случае можно предложить пользователю ввести код на странице авторизации Яндекс OAuth:

Чтобы пользователь подтвердил доступ к своим данным, настройте в приложении запрос для двух кодов: device_code для устройства и user_code для пользователя. Для этого используйте запрос кодов подтверждения.

Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново.
После получения кодов приложение одновременно:
- предлагает пользователю ввести user_code на странице Авторизация на устройстве;
- начинает периодически запрашивать OAuth-токен, передавая device_code.
Если код введен корректно, Яндекс OAuth предложит разрешить или запретить доступ приложению. Яндекс OAuth возвращает токен в ответ на следующий запрос приложения.

Запрос кодов подтверждения

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

Приложение должно запросить коды подтверждения с помощью HTTP-метода POST:

POST /device/code
Host: https://oauth.yandex.ru/

 & client_id=<идентификатор приложения>
[& device_id=<идентификатор устройства>]
[& device_name=<имя устройства>]
[& scope=<запрашиваемые необходимые права>]
[& optional_scope=<запрашиваемые опциональные права>]

Обязательные параметры

Параметр	Описание
`client_id`	Идентификатор приложения. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения.

Дополнительные параметры

Параметр	Описание
`device_id`	Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства. Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126). Подробнее о работе с токенами для отдельных устройств читайте на странице Отзыв токена для устройства. Если параметр `device_id` передан без параметра `device_name`, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства. Внимание У приложения не может быть больше 30 токенов, привязанных к устройствам определенного пользователя. Если Яндекс OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать.
`device_name`	Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов. Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д. Если параметр `device_name` передан без параметра `device_id`, он будет проигнорирован. Яндекс OAuth сможет выдать только обычный токен, не привязанный к устройству.
`scope`	Список прав доступа, необходимых приложению. Значения в списке разделяются пробелами. Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения. Если параметры `scope` и `optional_scope` не переданы, то токен будет выдан с правами, указанными при регистрации приложения.
`optional_scope`	Опциональные права запрашиваются в дополнение к правам, указанным в параметре `scope`. Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения. Пользователь может выбрать, какие из опциональных прав предоставить. Токен будет выдан с правами, указанными в параметре `scope`, и правами, выбранными пользователем из указанных в параметре `optional_scope`. Параметр можно использовать, например, если приложению нужна электронная почта для регистрации пользователя, а доступ к портрету желателен, но не обязателен. Примечание Права доступа, запрошенные одновременно через параметр `scope` и через параметр `optional_scope`, будут считаться опциональными.

Формат ответа

Запрос выполнен успешно

Запрос выполнен с ошибкой

Яндекс OAuth возвращает код для пользователя и информацию для запроса токена:

200 OK

Content-type: application/json

{
   "device_code": "3e2a5a5c0e02439aa78a23442721848c",
   "user_code": "h5nbcr6c",
   "verification_url": "https://oauth.yandex.ru/device",
   "interval": 5,
   "expires_in": 300
}

Параметры ответа:

Свойство	Описание
`device_code`	Код, с которым следует запрашивать OAuth-токен.
`user_code`	Код, который должен ввести пользователь, чтобы разрешить доступ к своим данным.
`verification_url`	Адрес страницы, на которой пользователь должен ввести код из свойства `user_code`: `https://oauth.yandex.ru/device`.
`interval`	Минимальный интервал в секундах, с которым приложение должно запрашивать OAuth-токен. Если запросы будут приходить чаще, Яндекс OAuth может ответить ошибкой.
`expires_in`	Срок действия пары кодов в секундах. По истечению этого срока получить токен для них будет невозможно — нужно будет начать процедуру сначала.

Если выдать токен не удалось, ответ содержит описание ошибки:

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

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

invalid_client ― приложение с указанным идентификатором (параметр client_id) не найдено или заблокировано. Этот код также возвращается, если в параметре client_secret передан неверный секретный ключ.
invalid_request ― неверный формат запроса (один из параметров не указан, указан дважды, или передан не в теле запроса).
unauthorized_client — приложение было отклонено при модерации или только ожидает ее. Также возвращается, если приложение заблокировано.
Basic auth required — тип авторизации, указанный в заголовке Authorization, отличен от Basic.
Malformed Authorization header — заголовок Authorization не соответствует формату <client_id>:<client_secret>, или эта строка не закодирована методом base64.

Обмен кода подтверждения на OAuth-токен

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

Приложение отправляет код устройства, а также свой идентификатор и пароль в POST-запросе.

POST /token HTTP/1.1
Host: https://oauth.yandex.ru/
Content-type: application/x-www-form-urlencoded
Content-Length: <длина тела запроса>
[Authorization: Basic <закодированная строка `client_id:client_secret`>]

   grant_type=device_code
 & code=<код устройства>
[& client_id=<идентификатор приложения>]
[& client_secret=<секретный ключ>]

Обязательные параметры

Параметр

Описание

grant_type

Способ запроса OAuth-токена.

Если вы используете код подтверждения для устройства, укажите значение device_code.

code

Код из параметра device_code, полученный на этапе запроса кодов подтверждения.

Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново.

Дополнительные параметры

Параметр

Описание

client_id

Идентификатор приложения. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения.

Секретный ключ и идентификатор приложения также можно передать в заголовке Authorization.

client_secret

Секретный ключ. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения.

Секретный ключ и идентификатор приложения также можно передать в заголовке Authorization.

Параметры запроса должны передаваться в теле запроса и должны быть закодированы в urlencode.

Примечание

Чтобы передать идентификатор и секретный ключ в заголовке Authorization, закодируйте строку <client_id>:<client_secret> методом base64.

Если Яндекс OAuth получает заголовок Authorization, параметры client_id и client_secret в теле запроса игнорируются.

Формат ответа

Запрос выполнен успешно

Запрос выполнен с ошибкой

Яндекс OAuth возвращает OAuth-токен, refresh-токен и время их жизни в JSON-формате:

200 OK
Content-type: application/json

{
  "token_type": "bearer",
  "access_token": "AQAAAACy1C6ZAAAAfa6vDLuItEy8pg-iIpnDxIs",
  "expires_in": 124234123534,
  "refresh_token": "1:GN686QVt0mmakDd9:A4pYuW9LGk0_UnlrMIWklkAuJkUWbq27loFekJVmSYrdfzdePBy7:A-2dHOmBxiXgajnD-kYOwQ",
  "scope": "login:info login:email login:avatar"
}

Параметры ответа:

Свойство	Описание
`token_type`	Тип выданного токена. Всегда принимает значение `bearer`.
`access_token`	OAuth-токен с правами, которые вы запросили или указали при регистрации приложения.
`expires_in`	Время жизни токена в секундах.
`refresh_token`	Токен, который можно использовать для продления срока жизни соответствующего OAuth-токена. Время жизни refresh-токена совпадает с временем жизни OAuth-токена.
`scope`	Права, запрошенные разработчиком или указанные при регистрации приложения. Поле `scope` является дополнительным и возвращается, если OAuth предоставил токен с меньшим набором прав, чем было запрошено.

Если выдать токен не удалось, ответ содержит описание ошибки:

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

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

authorization_pending — пользователь еще не ввел код подтверждения.
bad_verification_code — переданное значение параметра code не является 7-значным числом.
invalid_client ― приложение с указанным идентификатором (параметр client_id) не найдено или заблокировано. Этот код также возвращается, если в параметре client_secret передан неверный секретный ключ.
invalid_grant — неверный или просроченный код подтверждения.
invalid_request ― неверный формат запроса (один из параметров не указан, указан дважды, или передан не в теле запроса).
invalid_scope — права приложения изменились после генерации кода подтверждения.
unauthorized_client — приложение было отклонено при модерации или только ожидает ее. Также возвращается, если приложение заблокировано.
unsupported_grant_type ― недопустимое значение параметра grant_type.
Basic auth required — тип авторизации, указанный в заголовке Authorization, отличен от Basic.
Malformed Authorization header — заголовок Authorization не соответствует формату <client_id>:<client_secret>, или эта строка не закодирована методом base64.

Была ли статья полезна?

Получение кода подтверждения от пользователя

Этап 3. Получение информации о пользователе