Пользователь вводит код в приложении
Некоторые приложения (например, консольные или установленные на телевизорах Smart TV) не могут получить код подтверждения из URL. В этом случае пользователь должен самостоятельно получить код от Яндекс.OAuth и ввести его в приложении.
Получение токена в обмен на код, введенный пользователем:
Приложение открывает в браузере страницу Яндекс.OAuth, где пользователь может разрешить доступ к своим данным.
Если на устройстве, где установлено приложение, недоступен браузер, пользователю придется перейти по нужному адресу на своем компьютере. Чтобы вводить адрес было удобнее, предоставьте пользователю QR-код или короткую ссылку.
Пользователь переходит на открывшуюся страницу, или по короткой ссылке и разрешает доступ приложению.
Яндекс.OAuth выводит код подтверждения. (Для этого в свойстве приложения Callback URL нужно указать адрес
https://oauth.yandex.ru/verification_code
).Приложение отправляет POST-запрос с кодом.
Яндекс.OAuth возвращает токен в теле ответа.
Полученный токен можно сохранить в приложении и использовать для запросов к API до истечения времени его жизни. Токен должен быть доступен только вашему приложению, поэтому не рекомендуется сохранять его в куках браузера, открытых конфигурационных файлах и т. п.
Получение кода подтверждения
Приложение должно направить пользователя на Яндекс.OAuth по следующему адресу:
https://oauth.yandex.ru/authorize? response_type=code & client_id=<идентификатор приложения> [& device_id=<идентификатор устройства>] [& device_name=<имя устройства>] [& redirect_uri=<адрес перенаправления>] [& login_hint=<имя пользователя или электронный адрес>] [& scope=<запрашиваемые необходимые права>] [& optional_scope=<запрашиваемые опциональные права>] [& force_confirm=yes] [& state=<произвольная строка>]
Параметр Описание Обязательные параметры response_type
Требуемый ответ.
При запросе кода подтверждения следует указать значение «code».
client_id
Идентификатор приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства).
Дополнительные параметры device_id Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства.
Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126).
Ограничение. У приложения не может быть больше 20 токенов, привязанных к устройствам определенного пользователя. Если Яндекс.OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать.Подробнее о токенах для отдельных устройств читайте на странице Токен для устройства.
device_name Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов.
Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д.
Если параметр
device_name
передан без параметраdevice_id
, он будет проигнорирован. Яндекс.OAuth сможет выдать только обычный токен, не привязанный к устройству.Если параметр
device_id
передан без параметраdevice_name
, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства.redirect_uri URL, на который нужно перенаправить пользователя после того, как он разрешил или отказал приложению в доступе. По умолчанию используется первый Callback URI, указанный в настройках приложения (
).В значении параметра допустимо указывать только те адреса, которые перечислены в настройках приложения. Если совпадение неточное, параметр игнорируется.
login_hint Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс.Почты или Яндекс.Почты для домена.
Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс.OAuth проверяет авторизацию пользователя:
Если пользователь уже авторизован с нужным аккаунтом, Яндекс.OAuth просто запрашивает разрешение на доступ.
Если пользователь не авторизован с нужным аккаунтом, он увидит форму входа на Яндекс, в которой поле логина заполнено значением параметра. Помните, что токен не обязательно будет запрошен для указанного аккаунта: пользователь может стереть предзаполненный логин и войти с любым другим.
Если параметр указывает на несуществующий аккаунт, Яндекс.OAuth сможет только сообщить об этом пользователю. Приложению придется запрашивать токен заново.
scope Список необходимых приложению в данный момент прав доступа, разделенных пробелом. Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения.
Если параметры
scope
иoptional_scope
не переданы, то токен будет выдан с правами, указанными при регистрации приложения.Параметр позволяет получить токен только с теми правами, которые нужны приложению в данный момент.
Примечание. Права доступа, запрошенные одновременно через параметрscope
и через параметрoptional_scope
, будут считаться опциональными правами, без которых приложение может обойтись. Пользователь самостоятельно решает, какие из запрошенных опциональных прав предоставить, а какие нет.optional_scope Список разделенных пробелом опциональных прав доступа, без которых приложение может обойтись. Опциональные права запрашиваются в дополнение к правам, указанным в параметре
scope
. Опциональные права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения.Если параметры
scope
иoptional_scope
не переданы, то токен будет выдан с правами, указанными при регистрации приложения.Пользователь самостоятельно решает, какие из запрошенных опциональных прав предоставить, а какие нет. Токен будет выдан с правами, указанными в параметре
scope
, и правами, выбранными пользователем из указанных в параметреoptional_scope
.Параметр можно использовать, например, если приложению нужна электронная почта для регистрации пользователя, а доступ к портрету желателен, но не обязателен.
Примечание. Права доступа, запрошенные одновременно через параметрscope
и через параметрoptional_scope
, будут считаться опциональными.force_confirm Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса.
Параметр полезен, например, если пользователь вошел на сайт с одним аккаунтом Яндекса и хочет переключиться на другой аккаунт. Если параметр не использовать, пользователю придется явно менять аккаунт на каком-нибудь сервисе Яндекса или отзывать токен, выданный сайту.
Параметр обрабатывается, если для него указано значение «yes», «true» или «1». При любом другом значении параметр игнорируется.
state Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа.
Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.
Параметр Описание Обязательные параметры response_type
Требуемый ответ.
При запросе кода подтверждения следует указать значение «code».
client_id
Идентификатор приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства).
Дополнительные параметры device_id Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства.
Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126).
Ограничение. У приложения не может быть больше 20 токенов, привязанных к устройствам определенного пользователя. Если Яндекс.OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать.Подробнее о токенах для отдельных устройств читайте на странице Токен для устройства.
device_name Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов.
Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д.
Если параметр
device_name
передан без параметраdevice_id
, он будет проигнорирован. Яндекс.OAuth сможет выдать только обычный токен, не привязанный к устройству.Если параметр
device_id
передан без параметраdevice_name
, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства.redirect_uri URL, на который нужно перенаправить пользователя после того, как он разрешил или отказал приложению в доступе. По умолчанию используется первый Callback URI, указанный в настройках приложения (
).В значении параметра допустимо указывать только те адреса, которые перечислены в настройках приложения. Если совпадение неточное, параметр игнорируется.
login_hint Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс.Почты или Яндекс.Почты для домена.
Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс.OAuth проверяет авторизацию пользователя:
Если пользователь уже авторизован с нужным аккаунтом, Яндекс.OAuth просто запрашивает разрешение на доступ.
Если пользователь не авторизован с нужным аккаунтом, он увидит форму входа на Яндекс, в которой поле логина заполнено значением параметра. Помните, что токен не обязательно будет запрошен для указанного аккаунта: пользователь может стереть предзаполненный логин и войти с любым другим.
Если параметр указывает на несуществующий аккаунт, Яндекс.OAuth сможет только сообщить об этом пользователю. Приложению придется запрашивать токен заново.
scope Список необходимых приложению в данный момент прав доступа, разделенных пробелом. Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения.
Если параметры
scope
иoptional_scope
не переданы, то токен будет выдан с правами, указанными при регистрации приложения.Параметр позволяет получить токен только с теми правами, которые нужны приложению в данный момент.
Примечание. Права доступа, запрошенные одновременно через параметрscope
и через параметрoptional_scope
, будут считаться опциональными правами, без которых приложение может обойтись. Пользователь самостоятельно решает, какие из запрошенных опциональных прав предоставить, а какие нет.optional_scope Список разделенных пробелом опциональных прав доступа, без которых приложение может обойтись. Опциональные права запрашиваются в дополнение к правам, указанным в параметре
scope
. Опциональные права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения.Если параметры
scope
иoptional_scope
не переданы, то токен будет выдан с правами, указанными при регистрации приложения.Пользователь самостоятельно решает, какие из запрошенных опциональных прав предоставить, а какие нет. Токен будет выдан с правами, указанными в параметре
scope
, и правами, выбранными пользователем из указанных в параметреoptional_scope
.Параметр можно использовать, например, если приложению нужна электронная почта для регистрации пользователя, а доступ к портрету желателен, но не обязателен.
Примечание. Права доступа, запрошенные одновременно через параметрscope
и через параметрoptional_scope
, будут считаться опциональными.force_confirm Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса.
Параметр полезен, например, если пользователь вошел на сайт с одним аккаунтом Яндекса и хочет переключиться на другой аккаунт. Если параметр не использовать, пользователю придется явно менять аккаунт на каком-нибудь сервисе Яндекса или отзывать токен, выданный сайту.
Параметр обрабатывается, если для него указано значение «yes», «true» или «1». При любом другом значении параметр игнорируется.
state Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа.
Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.
Когда пользователь разрешает доступ к своим данным, Яндекс.OAuth выводит код подтверждения. Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново.
Обмен кода подтверждения на токен
Приложение отправляет код, а также свой идентификатор и пароль в POST-запросе.
POST /token HTTP/1.1
Host: oauth.yandex.ru
Content-type: application/x-www-form-urlencoded
Content-Length: <длина тела запроса>
[Authorization: Basic <закодированная строка client_id:client_secret
>]
grant_type=authorization_code
& code=<код подтверждения>
[& client_id=<идентификатор приложения>]
[& client_secret=<пароль приложения>]
[& device_id=<идентификатор устройства>]
[& device_name=<имя устройства>]
Параметр | Описание |
---|---|
Обязательные параметры | |
grant_type | Способ запроса OAuth-токена. Если вы используете код подтверждения, укажите значение «authorization_code». |
code | Код подтверждения, полученный от Яндекс.OAuth. Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново. |
Параметр | Описание |
Дополнительные параметры | |
client_id | Идентификатор приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства). Идентификатор и пароль приложения обязательно нужно передать либо в параметрах запроса, либо в заголовке Authorization. |
client_secret | Пароль приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства). Пароль и идентификатор приложения обязательно нужно передать либо в параметрах запроса, либо в заголовке Authorization. |
device_id | Идентификатор устройства, для которого запрашивается токен. Если идентификатор был задан в параметре device_id при запросе кода подтверждения, при запросе токена параметры |
device_name | Имя устройства, для которого запрашивается токен. Если при запросе кода подтверждения был передан параметр |
Параметр | Описание |
---|---|
Обязательные параметры | |
grant_type | Способ запроса OAuth-токена. Если вы используете код подтверждения, укажите значение «authorization_code». |
code | Код подтверждения, полученный от Яндекс.OAuth. Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново. |
Параметр | Описание |
Дополнительные параметры | |
client_id | Идентификатор приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства). Идентификатор и пароль приложения обязательно нужно передать либо в параметрах запроса, либо в заголовке Authorization. |
client_secret | Пароль приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства). Пароль и идентификатор приложения обязательно нужно передать либо в параметрах запроса, либо в заголовке Authorization. |
device_id | Идентификатор устройства, для которого запрашивается токен. Если идентификатор был задан в параметре device_id при запросе кода подтверждения, при запросе токена параметры |
device_name | Имя устройства, для которого запрашивается токен. Если при запросе кода подтверждения был передан параметр |
Идентификатор и пароль приложения также можно отправить в заголовке 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-токена. |
scope | Права, запрошенные разработчиком или указанные при регистрации приложения. Поле |
Свойство | Описание |
---|---|
token_type | Тип выданного токена. Всегда принимает значение «bearer». |
access_token | OAuth-токен с запрошенными правами или с правами, указанными при регистрации приложения. |
expires_in | Время жизни токена в секундах. |
refresh_token | Токен, который можно использовать для продления срока жизни соответствующего OAuth-токена. |
scope | Права, запрошенные разработчиком или указанные при регистрации приложения. Поле |
Время жизни refresh-токена совпадает с временем жизни 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.