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

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

Когда пользователь разрешает приложению доступ к своим данным, Яндекс OAuth перенаправляет его в приложение на адрес, указанный в поле Redirect URI при регистрации приложения.
Код подтверждения возвращается в URL перенаправления. Чтобы обменять код подтверждения на OAuth-токен, приложение должно отправить POST-запрос.

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

Для дополнительной защиты ваших данных при передаче в запросах можно использовать параметры, которые поддерживает расширение PKCE протокола OAuth 2.0: случайную строку code_verifier и преобразованную версию этой строки code_challenge, а также данные о методе преобразования — code_challenge_method.

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

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

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).

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

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

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

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

http://www.example.com/token?code=<код подтверждения>
[& state=<значение параметра state в запросе>]

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

Свойство

Описание

code

Код подтверждения, который можно обменять на OAuth-токен.

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

state

Строка состояния, которую Яндекс OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа. Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.

Если код подтверждения выдать не удалось, то Яндекс OAuth указывает в URL код ошибки и ее описание.

http://www.example.com/token?error=<код ошибки>
 & error_description=<описание ошибки>
[& state=<значение параметра state в запросе>]

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

unauthorized_client — приложение было отклонено при модерации или только ожидает ее. Также возвращается, если приложение заблокировано.

Обмен кода подтверждения на 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.

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

Альтернативный способ с кодом подтверждения

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