--- metadata: - name: generator content: Diplodoc Platform v5.44.0 alternate: - https://yandex.ru/dev/id/doc/en/codes/screen-code-oauth.md - https://yandex.ru/dev/id/doc/ru/codes/screen-code-oauth.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/id/doc/ru/llms.txt # Ввод кода на странице авторизации Яндекс OAuth На некоторых устройствах (например, на телевизорах) вводить код подтверждения в приложении может быть неудобно. В этом случае можно предложить пользователю ввести код на странице авторизации Яндекс OAuth: 1. Чтобы пользователь подтвердил доступ к своим данным, настройте в приложении запрос для двух кодов: `device_code` для устройства и `user_code` для пользователя. Для этого используйте [запрос кодов подтверждения](#code). Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново. 1. После [получения кодов](#code-response) приложение одновременно: * предлагает пользователю ввести `user_code` на странице [Авторизация на устройстве](https://oauth.yandex.ru/device); * начинает периодически [запрашивать OAuth-токен](#token), передавая `device_code`. 1. Если код введен корректно, Яндекс OAuth предложит разрешить или запретить доступ приложению. Яндекс OAuth возвращает токен в ответ на следующий запрос приложения. ## Запрос кодов подтверждения {#code} ### Формат запроса {#code-request} Приложение должно запросить коды подтверждения с помощью HTTP-метода POST: ``` POST /device/code Host: https://oauth.yandex.ru/ & client_id=<идентификатор приложения> [& device_id=<идентификатор устройства>] [& device_name=<имя устройства>] [& scope=<запрашиваемые необходимые права>] [& optional_scope=<запрашиваемые опциональные права>] ``` #### Обязательные параметры #| || **Параметр** | **Описание** || || `client_id` | Идентификатор приложения. Доступен в [свойствах приложения](https://yandex.ru/dev/id/doc/ru/register-client.md#app-params). Чтобы открыть свойства, перейдите в [Яндекс OAuth](https://oauth.yandex.ru/) и нажмите на название приложения. || |# #### Дополнительные параметры #| || **Параметр** | **Описание** || || `device_id` | Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать [UUID](https://ru.wikipedia.org/wiki/UUID) и использовать его при каждом запросе нового токена с данного устройства. Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые [ASCII](https://ru.wikipedia.org/wiki/ASCII)-символы (с кодами от 32 до 126). Подробнее о работе с токенами для отдельных устройств читайте на странице [Отзыв токена для устройства](https://yandex.ru/dev/id/doc/ru/tokens/token-invalidate.md#device-token). Если параметр `device_id` передан без параметра `device_name`, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства. {% note alert %} У приложения не может быть больше 30 токенов, привязанных к устройствам определенного пользователя. Если Яндекс OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать. {% endnote %} || || `device_name` | Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов. Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д. Если параметр `device_name` передан без параметра `device_id`, он будет проигнорирован. Яндекс OAuth сможет выдать только обычный токен, не привязанный к устройству. || || `scope` | Список прав доступа, необходимых приложению. Значения в списке разделяются пробелами. Права должны запрашиваться из перечня, определенного при [регистрации приложения](https://yandex.ru/dev/id/doc/ru/register-client.md#access). Узнать допустимые права можно по ссылке [https://oauth.yandex.ru/client//info](https://oauth.yandex.ru/client//info), указав вместо идентификатор приложения. Если параметры `scope` и `optional_scope` не переданы, то токен будет выдан с правами, указанными при регистрации приложения. || || `optional_scope` | Опциональные права запрашиваются в дополнение к правам, указанным в параметре `scope`. Права должны запрашиваться из перечня, определенного при [регистрации приложения](https://yandex.ru/dev/id/doc/ru/register-client.md#access). Узнать допустимые права можно по ссылке [https://oauth.yandex.ru/client//info](https://oauth.yandex.ru/client//info), указав вместо идентификатор приложения. Пользователь может выбрать, какие из опциональных прав предоставить. Токен будет выдан с правами, указанными в параметре `scope`, и правами, выбранными пользователем из указанных в параметре `optional_scope`. Параметр можно использовать, например, если приложению нужна электронная почта для регистрации пользователя, а доступ к портрету желателен, но не обязателен. {% note info %} Права доступа, запрошенные одновременно через параметр `scope` и через параметр `optional_scope`, будут считаться опциональными. {% endnote %} || |# ### Формат ответа {#code-response} {% list tabs %} - Запрос выполнен успешно Яндекс OAuth возвращает код для пользователя и информацию для запроса токена: ```json 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-токен](#token-request). || || `user_code` | Код, который должен ввести пользователь, чтобы разрешить доступ к своим данным. || || `verification_url` | Адрес страницы, на которой пользователь должен ввести код из свойства `user_code`: `https://oauth.yandex.ru/device`. || || `interval` | Минимальный интервал в секундах, с которым приложение должно запрашивать OAuth-токен. Если запросы будут приходить чаще, Яндекс OAuth может ответить ошибкой. || || `expires_in` | Срок действия пары кодов в секундах. По истечению этого срока получить токен для них будет невозможно — нужно будет начать процедуру сначала. || |# - Запрос выполнен с ошибкой Если выдать токен не удалось, ответ содержит описание ошибки: ```json { "error_description": "<описание ошибки>", "error": "<код ошибки>" } ``` Возможные коды ошибок: * `invalid_client` ― приложение с указанным идентификатором (параметр `client_id`) не найдено или заблокировано. Этот код также возвращается, если в параметре `client_secret` передан неверный секретный ключ. * `invalid_request` ― неверный формат запроса (один из параметров не указан, указан дважды, или передан не в теле запроса). * `unauthorized_client` — приложение было отклонено при модерации или только ожидает ее. Также возвращается, если приложение заблокировано. * `Basic auth required` — тип авторизации, указанный в заголовке `Authorization`, отличен от Basic. * `Malformed Authorization header` — заголовок `Authorization` не соответствует формату `:`, или эта строка не закодирована методом base64. {% endlist %} ## Обмен кода подтверждения на OAuth-токен {#token} ### Формат запроса {#token-request} Приложение отправляет код устройства, а также свой идентификатор и пароль в 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`, полученный на этапе [запроса кодов подтверждения](#code-response). Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново. || |# #### Дополнительные параметры #| || **Параметр** | **Описание** || || `client_id` | Идентификатор приложения. Доступен в [свойствах приложения](https://yandex.ru/dev/id/doc/ru/register-client.md#app-params). Чтобы открыть свойства, перейдите в [Яндекс OAuth](https://oauth.yandex.ru/) и нажмите на название приложения. Секретный ключ и идентификатор приложения также можно передать в [заголовке `Authorization`](#auth-header). || || `client_secret` | Секретный ключ. Доступен в [свойствах приложения](https://yandex.ru/dev/id/doc/ru/register-client.md#app-params). Чтобы открыть свойства, перейдите в [Яндекс OAuth](https://oauth.yandex.ru/) и нажмите на название приложения. Секретный ключ и идентификатор приложения также можно передать в [заголовке `Authorization`](#auth-header). || |# Параметры запроса должны передаваться в теле запроса и должны быть закодированы в urlencode. {% note info %} Чтобы передать идентификатор и секретный ключ в заголовке `Authorization`, закодируйте строку `:` методом base64. Если Яндекс OAuth получает заголовок `Authorization`, параметры `client_id` и `client_secret` в теле запроса игнорируются. {#auth-header} {% endnote %} ### Формат ответа {#token-response} {% list tabs %} - Запрос выполнен успешно Яндекс OAuth возвращает OAuth-токен, refresh-токен и время их жизни в JSON-формате: ```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-токен с правами, которые вы запросили или указали при [регистрации приложения](https://yandex.ru/dev/id/doc/ru/register-client.md#access). || || `expires_in` | [Время жизни](https://yandex.ru/dev/id/doc/ru/concepts/ya-oauth-intro.md#ttl) токена в секундах. || || `refresh_token` | Токен, который можно использовать для [продления срока жизни](https://yandex.ru/dev/id/doc/ru/tokens/refresh-client.md ) соответствующего OAuth-токена. [Время жизни](https://yandex.ru/dev/id/doc/ru/concepts/ya-oauth-intro.md#ttl) refresh-токена совпадает с временем жизни OAuth-токена.|| || `scope` | Права, запрошенные разработчиком или указанные при [регистрации приложения](https://yandex.ru/dev/id/doc/ru/register-client.md#access). Поле `scope` является дополнительным и возвращается, если OAuth предоставил токен с меньшим набором прав, чем было запрошено. || |# - Запрос выполнен с ошибкой Если выдать токен не удалось, ответ содержит описание ошибки: ```json { "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` не соответствует формату `:`, или эта строка не закодирована методом base64. {% endlist %}