Приложение запрашивает код
Приложение направляет пользователя на страницу Яндекс.OAuth, где он может разрешить доступ к своим данным.
Пользователь разрешает доступ приложению.
Яндекс.OAuth перенаправляет пользователя на адрес, указанный в поле Callback URL при регистрации приложения. Код подтверждения (или описание ошибки) передается в параметре URL перенаправления.
Приложение получает адрес перенаправления и извлекает код подтверждения.
Приложение отправляет POST-запрос с кодом.
Яндекс.OAuth возвращает токен в теле ответа.
Полученный токен можно сохранить в приложении и использовать для запросов к API до истечения времени его жизни. Токен должен быть доступен только вашему приложению, поэтому не рекомендуется сохранять его в куках браузера, открытых конфигурационных файлах и т. п.
Запрос кода подтверждения
Приложение должно направить пользователя на Яндекс.OAuth по следующему адресу:
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=<произвольная строка>]
Параметр | Описание |
---|---|
Обязательные параметры | |
response_type | Требуемый ответ. При запросе кода подтверждения следует указать значение «code». |
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-атак или идентификации пользователя, для которого запрашивается токен. |
Параметр | Описание |
---|---|
Обязательные параметры | |
response_type | Требуемый ответ. При запросе кода подтверждения следует указать значение «code». |
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-атак или идентификации пользователя, для которого запрашивается токен. |
Получение кода подтверждения из URL
Когда пользователь разрешает доступ к своим данным, Яндекс.OAuth перенаправляет его в приложение. Код подтверждения включается в URL перенаправления.
Формат URL с кодом:
http://www.example.com/token?
code=<код подтверждения>
[& state=<значение параметра state в запросе>]
Параметр | Описание |
---|---|
code | Код подтверждения, который можно обменять на OAuth-токен. Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново. |
state | Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа. Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен. |
Параметр | Описание |
---|---|
code | Код подтверждения, который можно обменять на OAuth-токен. Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново. |
state | Строка состояния, которую Яндекс.OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа. Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен. |
Если код подтверждения выдать не удалось, то Яндекс.OAuth указывает в URL код ошибки и ее описание. Описание приводится на языке домена OAuth, к которому был отправлен запрос: например, для oauth.yandex.ru
будет возвращен текст на русском.
Формат URL с данными об ошибке:
http://www.example.com/token?
error=<код ошибки>
& error_description=<описание ошибки>
[& state=<значение параметра state в запросе>]
Возможные коды ошибок:
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=<код подтверждения>
[& client_id=<идентификатор приложения>]
[& client_secret=<пароль приложения>]
[& device_id=<идентификатор устройства>]
[& device_name=<имя устройства>]
Параметр | Описание |
---|---|
Обязательные параметры | |
grant_type | Способ запроса OAuth-токена. Если вы используете код подтверждения, укажите значение «authorization_code». |
code | Код подтверждения, полученный от Яндекс.OAuth. Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново. |
Дополнительные параметры | |
client_id | Идентификатор приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства). Пароль и идентификатор приложения также можно передать в заголовке Authorization. |
client_secret | Пароль приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства). Пароль и идентификатор приложения также можно передать в заголовке Authorization. |
device_id | Идентификатор устройства, для которого запрашивается токен. Если идентификатор был задан в параметре device_id при запросе кода подтверждения, при запросе токена параметры |
device_name | Имя устройства, для которого запрашивается токен. Если при запросе кода подтверждения был передан параметр |
Параметр | Описание |
---|---|
Обязательные параметры | |
grant_type | Способ запроса OAuth-токена. Если вы используете код подтверждения, укажите значение «authorization_code». |
code | Код подтверждения, полученный от Яндекс.OAuth. Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново. |
Дополнительные параметры | |
client_id | Идентификатор приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства). Пароль и идентификатор приложения также можно передать в заголовке Authorization. |
client_secret | Пароль приложения. Доступен в свойствах приложения (нажмите название приложения, чтобы открыть его свойства). Пароль и идентификатор приложения также можно передать в заголовке Authorization. |
device_id | Идентификатор устройства, для которого запрашивается токен. Если идентификатор был задан в параметре device_id при запросе кода подтверждения, при запросе токена параметры |
device_name | Имя устройства, для которого запрашивается токен. Если при запросе кода подтверждения был передан параметр |
Идентификатор и пароль приложения также можно отправить в заголовке 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-токена. |
scope | Права, запрошенные разработчиком или указанные при регистрации приложения. Поле |
Свойство | Описание |
---|---|
token_type | Тип выданного токена. Всегда принимает значение «bearer». |
access_token | OAuth-токен с запрошенными правами или с правами, указанными при регистрации приложения. |
expires_in | Время жизни токена в секундах. |
refresh_token | Токен, который можно использовать для продления срока жизни соответствующего OAuth-токена. |
scope | Права, запрошенные разработчиком или указанные при регистрации приложения. Поле |
Время жизни refresh-токена совпадает с временем жизни 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.