Веб-приложение
Получение токена для веб-приложения:
Приложение направляет пользователя на страницу Яндекс.OAuth, где он может разрешить доступ к своим данным.
Пользователь разрешает доступ приложению.
Яндекс.OAuth перенаправляет пользователя на адрес, указанный в поле Callback URL при регистрации. Данные о токене передаются в URL перенаправления после символа #.
Серверная среда может не передавать веб-приложению эту часть URL. В таком случае можно выделять данные из адреса с помощью JavaScript, или получать токены с помощью кода подтверждения.
Приложение получает адрес перенаправления и извлекает токен.
Полученный токен можно сохранить в приложении и использовать для запросов к API до истечения времени его жизни. Токен должен быть доступен только вашему приложению, поэтому не рекомендуется сохранять его в куках браузера, открытых конфигурационных файлах и т. п.
URL для запроса токена
Приложение должно направить пользователя на Яндекс.OAuth по следующему адресу:
https://oauth.yandex.ru/authorize?
response_type=token
& client_id=<идентификатор приложения>
[& device_id=<идентификатор устройства>]
[& device_name=<имя устройства>]
[& redirect_uri=<адрес перенаправления>]
[& login_hint=<имя пользователя или электронный адрес>]
[& scope=<запрашиваемые необходимые права>]
[& optional_scope=<запрашиваемые опциональные права>]
[& force_confirm=yes]
[& state=<произвольная строка>]
[& display=popup]
Параметр | Описание |
---|---|
Обязательные параметры | |
response_type | Требуемый ответ. При запросе токена следует указать значение «token». |
client_id | Идентификатор приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства). |
Дополнительные параметры | |
device_id | Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства. Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126). Ограничение. У приложения не может быть больше 20 токенов, привязанных к устройствам определенного пользователя. Если Яндекс.OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать. Подробнее о токенах для отдельных устройств читайте на странице Токен для устройства. |
device_name | Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов. Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д. Если параметр Если параметр |
redirect_uri | URL, на который нужно перенаправить пользователя после того, как он разрешил или отказал приложению в доступе. По умолчанию используется первый Callback URI, указанный в настройках приложения ( ).В значении параметра допустимо указывать только те адреса, которые перечислены в настройках приложения. Если совпадение неточное, параметр игнорируется. |
login_hint | Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс.Почты или Яндекс.Почты для домена. Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс.OAuth проверяет авторизацию пользователя:
Если параметр указывает на несуществующий аккаунт, Яндекс.OAuth сможет только сообщить об этом пользователю. Приложению придется запрашивать токен заново. |
scope | Список необходимых приложению в данный момент прав доступа, разделенных пробелом. Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения. Если параметры Параметр позволяет получить токен только с теми правами, которые нужны приложению в данный момент. Примечание. Права доступа, запрошенные одновременно через параметр scope и через параметр optional_scope , будут считаться опциональными правами, без которых приложение может обойтись. Пользователь самостоятельно решает, какие из запрошенных опциональных прав предоставить, а какие нет. |
optional_scope | Список разделенных пробелом опциональных прав доступа, без которых приложение может обойтись. Опциональные права запрашиваются в дополнение к правам, указанным в параметре Если параметры Пользователь самостоятельно решает, какие из запрошенных опциональных прав предоставить, а какие нет. Токен будет выдан с правами, указанными в параметре Параметр можно использовать, например, если приложению нужна электронная почта для регистрации пользователя, а доступ к портрету желателен, но не обязателен. Примечание. Права доступа, запрошенные одновременно через параметр scope и через параметр optional_scope , будут считаться опциональными. |
force_confirm | Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса. Параметр полезен, например, если пользователь вошел на сайт с одним аккаунтом Яндекса и хочет переключиться на другой аккаунт. Если параметр не использовать, пользователю придется явно менять аккаунт на каком-нибудь сервисе Яндекса или отзывать токен, выданный сайту. Параметр обрабатывается, если для него указано значение «yes», «true» или «1». При любом другом значении параметр игнорируется. |
state | Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа. Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен. |
display | Признак облегченной верстки (без стандартной навигации Яндекса) для страницы разрешения доступа. Облегченную верстку стоит запрашивать, например, если страницу разрешения нужно отобразить в маленьком всплывающем окне. Обрабатывается только значение «popup». Другие значения игнорируются. |
Параметр | Описание |
---|---|
Обязательные параметры | |
response_type | Требуемый ответ. При запросе токена следует указать значение «token». |
client_id | Идентификатор приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства). |
Дополнительные параметры | |
device_id | Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства. Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126). Ограничение. У приложения не может быть больше 20 токенов, привязанных к устройствам определенного пользователя. Если Яндекс.OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать. Подробнее о токенах для отдельных устройств читайте на странице Токен для устройства. |
device_name | Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов. Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д. Если параметр Если параметр |
redirect_uri | URL, на который нужно перенаправить пользователя после того, как он разрешил или отказал приложению в доступе. По умолчанию используется первый Callback URI, указанный в настройках приложения ( ).В значении параметра допустимо указывать только те адреса, которые перечислены в настройках приложения. Если совпадение неточное, параметр игнорируется. |
login_hint | Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс.Почты или Яндекс.Почты для домена. Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс.OAuth проверяет авторизацию пользователя:
Если параметр указывает на несуществующий аккаунт, Яндекс.OAuth сможет только сообщить об этом пользователю. Приложению придется запрашивать токен заново. |
scope | Список необходимых приложению в данный момент прав доступа, разделенных пробелом. Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения. Если параметры Параметр позволяет получить токен только с теми правами, которые нужны приложению в данный момент. Примечание. Права доступа, запрошенные одновременно через параметр scope и через параметр optional_scope , будут считаться опциональными правами, без которых приложение может обойтись. Пользователь самостоятельно решает, какие из запрошенных опциональных прав предоставить, а какие нет. |
optional_scope | Список разделенных пробелом опциональных прав доступа, без которых приложение может обойтись. Опциональные права запрашиваются в дополнение к правам, указанным в параметре Если параметры Пользователь самостоятельно решает, какие из запрошенных опциональных прав предоставить, а какие нет. Токен будет выдан с правами, указанными в параметре Параметр можно использовать, например, если приложению нужна электронная почта для регистрации пользователя, а доступ к портрету желателен, но не обязателен. Примечание. Права доступа, запрошенные одновременно через параметр scope и через параметр optional_scope , будут считаться опциональными. |
force_confirm | Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса. Параметр полезен, например, если пользователь вошел на сайт с одним аккаунтом Яндекса и хочет переключиться на другой аккаунт. Если параметр не использовать, пользователю придется явно менять аккаунт на каком-нибудь сервисе Яндекса или отзывать токен, выданный сайту. Параметр обрабатывается, если для него указано значение «yes», «true» или «1». При любом другом значении параметр игнорируется. |
state | Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа. Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен. |
display | Признак облегченной верстки (без стандартной навигации Яндекса) для страницы разрешения доступа. Облегченную верстку стоит запрашивать, например, если страницу разрешения нужно отобразить в маленьком всплывающем окне. Обрабатывается только значение «popup». Другие значения игнорируются. |
Ответ Яндекс.OAuth
Данные о токене передаются в URL перенаправления после символа #.Если серверная среда не позволяет приложению получить эту часть URL, данные можно извлечь с помощью JavaScript, или получать токены с помощью кода подтверждения.
Формат URL с токеном:
http://www.example.com/token#
access_token=<новый OAuth-токен>
& expires_in=<время жизни токена в секундах>
& token_type=bearer
[& state=<значение параметра state в запросе>]
[& scope=<права доступа>]
Параметр | Описание |
---|---|
access_token | OAuth-токен с запрошенными правами или с правами, указанными при регистрации приложения. |
expires_in | Время жизни токена в секундах. |
token_type | Тип выданного токена. Всегда принимает значение «bearer». |
state | Значение параметра |
scope | Права, запрошенные разработчиком или указанные при регистрации приложения. Поле |
Параметр | Описание |
---|---|
access_token | OAuth-токен с запрошенными правами или с правами, указанными при регистрации приложения. |
expires_in | Время жизни токена в секундах. |
token_type | Тип выданного токена. Всегда принимает значение «bearer». |
state | Значение параметра |
scope | Права, запрошенные разработчиком или указанные при регистрации приложения. Поле |
Если токен выдать не удалось, то Яндекс.OAuth добавляет к адресу код и описание ошибки. Описание приводится на языке домена OAuth, к которому был отправлен запрос: например, для oauth.yandex.ru
будет возвращен текст на русском.
Формат URL с данными об ошибке:
http://www.example.com/token#
error=<код ошибки>
& error_description=<описание ошибки>
[& state=<значение параметра state в запросе>]
Возможные коды ошибок:
access_denied
— пользователь отказал приложению в доступе.unauthorized_client
— приложение было отклонено при модерации или только ожидает ее. Также возвращается, если приложение заблокировано.
Выделение данных из URL с помощью JavaScript
Часть адреса после символа # доступна в JavaScript-свойстве document.location.hash
.
Например, токен можно получить следующим образом:
var token = /access_token=([^&]+)/.exec(document.location.hash)[1];