Мобильное приложение

Получение токена для мобильного приложения:

Приложение направляет пользователя на страницу Яндекс.OAuth, где он может разрешить доступ к своим данным. Страницу можно открыть в браузере или в элементе WebView, встроенном в приложение.
Пользователь разрешает доступ приложению.
Яндекс.OAuth перенаправляет пользователя на адрес, указанный в поле Callback URL при регистрации приложения. Данные о токене передаются в URL перенаправления после символа #.

Чтобы перехватить URL из браузера, в адресе можно использовать собственную схему URI, например myapp://token . Переход по такому URL запустит приложение, которое зарегистрировано в операционной системе как обработчик схемы myapp.
Приложение получает адрес перенаправления и извлекает токен.

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

Полученный токен можно сохранить в приложении и использовать для запросов к 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 символов. Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д. Если параметр `device_name` передан без параметра `device_id`, он будет проигнорирован. Яндекс.OAuth сможет выдать только обычный токен, не привязанный к устройству. Если параметр `device_id` передан без параметра `device_name`, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства.
redirect_uri	URL, на который нужно перенаправить пользователя после того, как он разрешил или отказал приложению в доступе. По умолчанию используется первый Callback URI, указанный в настройках приложения (Платформы → Веб-сервисы → 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-атак или идентификации пользователя, для которого запрашивается токен.
display	Признак облегченной верстки (без стандартной навигации Яндекса) для страницы разрешения доступа. Облегченную верстку стоит запрашивать, например, если страницу разрешения нужно отобразить в маленьком всплывающем окне. Обрабатывается только значение «popup». Другие значения игнорируются.


Параметр	Описание
Обязательные параметры
response_type	Требуемый ответ. При запросе токена следует указать значение «token».
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, указанный в настройках приложения (Платформы → Веб-сервисы → 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-атак или идентификации пользователя, для которого запрашивается токен.
display	Признак облегченной верстки (без стандартной навигации Яндекса) для страницы разрешения доступа. Облегченную верстку стоит запрашивать, например, если страницу разрешения нужно отобразить в маленьком всплывающем окне. Обрабатывается только значение «popup». Другие значения игнорируются.

Ответ Яндекс.OAuth

Данные о токене передаются в URL перенаправления после символа #.

Формат URL с токеном:

myapp://token#
   access_token=<новый OAuth-токен>     
 & expires_in=<время жизни токена в секундах>
 & token_type=bearer
[& state=<значение параметра state, переданное в запросе>]
[& scope=<права доступа>]


Параметр	Описание
`access_token`	OAuth-токен с запрошенными правами или с правами, указанными при регистрации приложения.
`expires_in`	Время жизни токена в секундах.
`token_type`	Тип выданного токена. Всегда принимает значение «bearer».
`state`	Значение параметра `state` из исходного запроса, если этот параметр был передан.
`scope`	Права, запрошенные разработчиком или указанные при регистрации приложения. Поле `scope` является дополнительным и возвращается, если OAuth предоставил токен с меньшим набором прав, чем было запрошено.


Параметр	Описание
`access_token`	OAuth-токен с запрошенными правами или с правами, указанными при регистрации приложения.
`expires_in`	Время жизни токена в секундах.
`token_type`	Тип выданного токена. Всегда принимает значение «bearer».
`state`	Значение параметра `state` из исходного запроса, если этот параметр был передан.
`scope`	Права, запрошенные разработчиком или указанные при регистрации приложения. Поле `scope` является дополнительным и возвращается, если OAuth предоставил токен с меньшим набором прав, чем было запрошено.

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

myapp://token#
  state=<значение параметра state в запросе>
& error=<код ошибки>

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

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