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

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

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

Совет

Если на устройстве, где установлено приложение, недоступен браузер, пользователю придется перейти по нужному адресу на своем компьютере. Чтобы вводить адрес было удобнее, предоставьте пользователю QR-код или короткую ссылку.
Код подтверждения отобразится в браузере. Для этого в свойстве приложения Redirect URI при регистрации приложения нужно указать адрес https://oauth.yandex.ru/verification_code.
Чтобы обменять код подтверждения на OAuth-токен, приложение должно отправить POST-запрос.

Полученный токен можно сохранить в приложении и использовать для запросов к API до истечения времени его жизни. Токен должен быть доступен только вашему приложению, поэтому не рекомендуется сохранять его в браузере или открытых конфигурационных файлах.

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

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

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=<произвольная строка>]
[& code_challenge=<преобразованная верcия верификатора code_verifier>]
[& code_challenge_method=<метод преобразования>]

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

Параметр	Описание
`response_type`	Требуемый ответ. При запросе кода подтверждения следует указать значение code.
`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 сможет выдать только обычный токен, не привязанный к устройству.
`redirect_uri`	URL, на который нужно перенаправить пользователя после того, как он разрешил приложению доступ. По умолчанию используется первый Redirect URI, указанный в настройках приложения (Платформы → Веб-сервисы → Redirect URI). В значении параметра допустимо указывать только те адреса, которые перечислены в настройках приложения. Если совпадение неточное, параметр игнорируется.
`login_hint`	Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс Почты или Яндекс Почты для домена. Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс OAuth проверяет авторизацию пользователя: Если пользователь уже авторизован с нужным аккаунтом, Яндекс OAuth просто запрашивает разрешение на доступ. Если пользователь не авторизован с нужным аккаунтом, он увидит форму входа на Яндекс, в которой поле логина заполнено значением параметра. Помните, что токен не обязательно будет запрошен для указанного аккаунта: пользователь может стереть предзаполненный логин и войти с любым другим. Если параметр указывает на несуществующий аккаунт, Яндекс 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`, будут считаться опциональными.
`force_confirm`	Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса. Параметр полезен, например, если пользователь вошел на сайт с одним аккаунтом Яндекса и хочет переключиться на другой аккаунт. Если параметр не использовать, пользователю придется явно менять аккаунт на каком-нибудь сервисе Яндекса или отзывать токен, выданный сайту. Параметр обрабатывается, если для него указано значение `yes`, `true` или `1`. При любом другом значении параметр игнорируется.
`state`	Строка состояния, которую Яндекс OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа. Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.
`code_challenge`	Версия верификатора `code_verifier`, преобразованная с помощью `code_challenge_method`. Применяется при использовании расширения PKCE для защиты передаваемых данных. Генерируется приложением для последующей проверки, что запрос токена поступает от того же приложения, которое запросило авторизацию.
`code_challenge_method`	Метод преобразования `code_verifier` в `code_challenge`. Возможные значения: `S256` (предпочтительное) и `plain` (для случаев, когда невозможно использовать S256).

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

Когда пользователь разрешает доступ к своим данным, Яндекс OAuth отобразит код подтверждения:

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

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

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

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

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

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

Параметр

Описание

grant_type

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

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

code

Код подтверждения, полученный от Яндекс OAuth.

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

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

Параметр	Описание
`client_id`	Идентификатор приложения. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения. Секретный ключ и идентификатор приложения также можно передать в заголовке `Authorization`.
`client_secret`	Секретный ключ. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения. Секретный ключ и идентификатор приложения также можно передать в заголовке `Authorization`. Если для защиты данных применяется расширение PKCE и в запросе передается параметр `code_verifier`, то секретный ключ передавать не требуется.
`device_id`	Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства. Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126). Подробнее о работе с токенами для отдельных устройств читайте на странице Отзыв токена для устройства. Если параметр `device_id` передан без параметра `device_name`, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства. Внимание У приложения не может быть больше 30 токенов, привязанных к устройствам определенного пользователя. Если Яндекс OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать.
`device_name`	Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов. Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д. Если параметр `device_name` передан без параметра `device_id`, он будет проигнорирован. Яндекс OAuth сможет выдать только обычный токен, не привязанный к устройству.
`code_verifier`	Верификатор, обеспечивающий защиту передаваемых данных. Параметр применяется при использовании расширения PKCE. Представляет собой случайную строку, сгенерированную приложением, на основании которой формируется `code_challenge`. Сервер преобразует `code_verifier` методом `code_challenge_method`, полученным в запросе на отправку кода подтверждения, и сверяет результат с `code_challenge` из того же запроса.

Параметры запроса должны передаваться в теле запроса и должны быть закодированы в 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.

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

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

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