Документация

Токен по коду, полученному автоматически

Получение токена в обмен на код, извлеченный из URL:

  1. Приложение направляет пользователя на страницу Яндекс.OAuth, где он может разрешить доступ к своим данным.

  2. Пользователь разрешает доступ приложению.

  3. Яндекс.OAuth перенаправляет пользователя на адрес, указанный в поле Callback URL при регистрации приложения. Код подтверждения (или описание ошибки) передается в параметре URL перенаправления.

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

  5. Приложение отправляет POST-запрос с кодом.

  6. Яндекс.OAuth возвращает токен в теле ответа.

Совет. Токены для отладки приложения можно получать вручную.

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

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

Приложение должно направить пользователя на Яндекс.OAuth по следующему адресу:

https://oauth.yandex.ru/authorize?
   response_type
[no-highlight[

Требуемый ответ.

При запросе кода подтверждения следует указать значение «code».

]no-highlight]
=code & client_id
[no-highlight[

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

]no-highlight]
=<идентификатор приложения> [& device_id
[no-highlight[

Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства.

Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126).

Ограничение. У приложения не может быть больше 20 токенов, привязанных к устройствам определенного пользователя. Если Яндекс.OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать.

Подробнее о токенах для отдельных устройств читайте на странице Токен для устройства.

]no-highlight]
=<идентификатор устройства>] [& device_name
[no-highlight[

Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов.

Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д.

Если параметр device_name передан без параметра device_id, он будет проигнорирован. Яндекс.OAuth сможет выдать только обычный токен, не привязанный к устройству.

Если параметр device_id передан без параметра device_name, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства.

]no-highlight]
=<имя устройства>] [& login_hint
[no-highlight[

Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс.Почты или Яндекс.Почты для домена.

Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс.OAuth проверяет авторизацию пользователя:

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

  • Если пользователь не авторизован с нужным аккаунтом, он увидит форму входа на Яндекс, в которой поле логина заполнено значением параметра. Помните, что токен не обязательно будет запрошен для указанного аккаунта: пользователь может стереть предзаполненный логин и войти с любым другим.

Если параметр указывает на несуществующий аккаунт, Яндекс.OAuth сможет только сообщить об этом пользователю. Приложению придется запрашивать токен заново.

]no-highlight]
=<имя пользователя или электронный адрес>] [& force_confirm
[no-highlight[

Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса.

Параметр полезен, например, если пользователь вошел на сайт с одним аккаунтом Яндекса и хочет переключиться на другой аккаунт. Если параметр не использовать, пользователю придется явно менять аккаунт на каком-нибудь сервисе Яндекса или отзывать токен, выданный сайту.

Параметр обрабатывается, если для него указано значение «yes», «true» или «1». При любом другом значении параметр игнорируется.

]no-highlight]
=yes] [& state
[no-highlight[

Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа.

Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.

]no-highlight]
=<произвольная строка>]
ПараметрОписание
Обязательные параметры

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, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства.

login_hint

Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс.Почты или Яндекс.Почты для домена.

Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс.OAuth проверяет авторизацию пользователя:

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

  • Если пользователь не авторизован с нужным аккаунтом, он увидит форму входа на Яндекс, в которой поле логина заполнено значением параметра. Помните, что токен не обязательно будет запрошен для указанного аккаунта: пользователь может стереть предзаполненный логин и войти с любым другим.

Если параметр указывает на несуществующий аккаунт, Яндекс.OAuth сможет только сообщить об этом пользователю. Приложению придется запрашивать токен заново.

force_confirm

Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса.

Параметр полезен, например, если пользователь вошел на сайт с одним аккаунтом Яндекса и хочет переключиться на другой аккаунт. Если параметр не использовать, пользователю придется явно менять аккаунт на каком-нибудь сервисе Яндекса или отзывать токен, выданный сайту.

Параметр обрабатывается, если для него указано значение «yes», «true» или «1». При любом другом значении параметр игнорируется.

state

Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа.

Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.

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

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

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

Формат URL с кодом:

http://www.example.com/token?
   code
[no-highlight[

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

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

]no-highlight]
=<код подтверждения> [& state
[no-highlight[

Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа.

Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.

]no-highlight]
=<значение параметра state
[no-highlight[

Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа.

Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.

]no-highlight]
в запросе>]
ПараметрОписание
code

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

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

state

Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа.

Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.

Если код подтверждения выдать не удалось, то Яндекс.OAuth указывает в URL код ошибки и ее описание. Описание приводится на языке домена OAuth, к которому был отправлен запрос: например, для oauth.yandex.ru будет возвращен текст на русском.

Формат URL с данными об ошибке:

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

Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа.

Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.

]no-highlight]
в запросе>]

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

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

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

Приложение отправляет код, а также свой идентификатор и пароль в 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
[no-highlight[

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

]no-highlight]
=<код подтверждения> [& client_id
[no-highlight[

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

]no-highlight]
=<идентификатор приложения>] [& client_secret
[no-highlight[

Пароль приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства).

Пароль и идентификатор приложения также можно передать в заголовке Authorization.

]no-highlight]
=<пароль приложения>] [& device_id
[no-highlight[

Идентификатор устройства, для которого запрашивается токен.

Если идентификатор был задан в параметре device_id при запросе кода подтверждения, при запросе токена параметры device_id и device_name игнорируются.

]no-highlight]
=<идентификатор устройства>] [& device_name
[no-highlight[

Имя устройства, для которого запрашивается токен.

Если при запросе кода подтверждения был передан параметр device_id, при запросе токена параметры device_id и device_name игнорируются.

]no-highlight]
=<имя устройства>]
ПараметрОписание
Обязательные параметры

grant_type

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

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

code

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

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

client_id

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

client_secret

Пароль приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства).

Пароль и идентификатор приложения также можно передать в заголовке Authorization.

device_id

Идентификатор устройства, для которого запрашивается токен.

Если идентификатор был задан в параметре device_id при запросе кода подтверждения, при запросе токена параметры device_id и device_name игнорируются.

device_name

Имя устройства, для которого запрашивается токен.

Если при запросе кода подтверждения был передан параметр device_id, при запросе токена параметры device_id и device_name игнорируются.

Идентификатор и пароль приложения также можно отправить в заголовке Authorization, закодировав строку <client_id>:<client_secret> методом base64. Если Яндекс.OAuth получает заголовок Authorization, параметры client_id и client_secret в теле запроса игнорируются.

Формат ответа с токеном

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

200 OK
Content-type: application/json

{
  "access_token
[no-highlight[

OAuth-токен с правами, указанными при регистрации приложения.

]no-highlight]
": "5fd980a5133b4887a8937fe07d3a0a60", "token_type
[no-highlight[

Тип выданного токена. Всегда принимает значение «bearer».

]no-highlight]
": "bearer", "expires_in
[no-highlight[

Время жизни токена в секундах.

]no-highlight]
": 124234123534 }
КлючОписание
access_token

OAuth-токен с правами, указанными при регистрации приложения.

token_type

Тип выданного токена. Всегда принимает значение «bearer».

expires_in

Время жизни токена в секундах.

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

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

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

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