Приложение запрашивает код. Войти через Яндекс. Руководство разработчика
Получение токена в обмен на код, извлеченный из URL:Приложение направляет пользователя на страницу Яндекс.OAuth, где он может разрешить доступ к своим данным.
Пользователь разрешает доступ к приложению.
Яндекс.OAuth перенаправляет пользователя на URL, указанный в поле Callback URL при регистрации приложения. Код подтверждения (или описание ошибки) передается в параметре URL-адреса перенаправления.
Приложение получает адрес переадресации и код подтверждения.
Приложение отправляет POST-запрос с кодом.
Яндекс.OAuth возвращает токен в теле ответа.
Совет. Вы можете получить токены отладки для приложения вручную.
Токен можно сохранить в приложении и использовать для запросов API до истечения срока его действия. Токен должен быть доступен только вашему приложению, поэтому мы не рекомендуем сохранять его в файлах cookie браузера, открывать файлы конфигурации и т.
Приложение должно направить пользователя на Яндекс.OAuth по следующему адресу:
https://oauth.yandex.com/authorize? \nОжидаемый ответ.
\nПри запросе кода подтверждения укажите значение «код».
\n "}}">=код & \nИдентификатор приложения. Доступно в свойствах приложения (щелкните имя приложения, чтобы открыть его свойства).
\n "}}">=<идентификатор приложения> [&\nУникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, просто сгенерируйте UUID один раз и используйте его каждый раз, когда с этого устройства запрашивается новый токен.
\n \nИдентификатор должен содержать от 6 до 50 символов. Допускаются только печатные символы ASCII (с кодами от 32 до 126).
\nОграничение. Приложение может иметь до 20 токенов, связанных с устройствами пользователя. Если Яндекс.OAuth выдает новый токен устройства для приложения, самый старый токен перестает работать.
\nДополнительные сведения о токенах для отдельных устройств см. в разделе Токен для устройства.
\n "}}">=<идентификатор устройства>] [&\nИмя устройства для отображения пользователям. До 100 символов.
\nДля мобильных устройств рекомендуется передавать имя устройства, указанное пользователем. Если имя отсутствует, его можно взять из модели устройства, названия и версии ОС и т. д.
\nЕсли
имя_устройства 9Параметр 0055 отправляется без параметра
device_id
, он игнорируется. Яндекс.OAuth может выдать только обычный токен, не привязанный к устройству.\n Если параметр
\n "}}">=<имя устройства>] [& \ndevice_id
отправляется без параметраdevice_name
, токен помечается как выданный для неизвестного устройства в пользовательском интерфейсе.URL-адрес для перенаправления пользователя после того, как он разрешит или запретит доступ к приложению. По умолчанию используется первый URI обратного вызова, указанный в настройках приложения (Платформы → Веб-сервисы → URI обратного вызова).
\nЗначение параметра может содержать только URL-адреса, указанные в настройках приложения. Если совпадение неточное, этот параметр игнорируется.
\n "}}">=] [& \n Явное указание учетной записи, для которой запрашивается токен. В значении параметра можно передать имя пользователя аккаунта Яндекса, а также адрес Яндекс.Почты или Яндекс.Почты для домена.
\nЭтот параметр позволяет помочь пользователю авторизоваться в Яндексе с той учетной записью, к которой приложению необходим доступ. Когда Яндекс.OAuth получает этот параметр, он проверяет пользователя'.;s авторизация:
\n \nЕсли в этом параметре указан несуществующий аккаунт, Яндекс.OAuth сможет только сообщить об этом пользователю. Приложению придется снова запросить токен.
\n "}}">=<имя пользователя или адрес электронной почты>] [& \nСписок прав доступа, необходимых приложению в данный момент, разделенных пробелом. Права необходимо запрашивать из списка, определенного при регистрации приложения. Чтобы посмотреть разрешенные права, перейдите по ссылке https://oauth.yandex.com/client/<client_id>/info, указав идентификатор приложения вместо <client_id>.
\n Если параметры
\nscope
иoption_scope
не переданы, то токен будет выдан с правами, указанными при регистрации приложения.Этот параметр позволяет получить токен только с теми правами, которые в данный момент требуются приложению.
\n\n
Примечание. Все права доступа запрашиваются сразу через параметры
scope
иoption_scope
, считаются необязательными и не требуются для работы приложения. Пользователь решает, какие запрошенные дополнительные права предоставить.\n
\n "}}">=<запрошенные необходимые права>] [& \nСписок дополнительных прав доступа, разделенных пробелом, которые не требуются для работы приложения. Дополнительные права запрашиваются в дополнение к правам, указанным в параметре области
\n. Дополнительные права должны быть запрошены из списка, определенного при регистрации приложения. Чтобы посмотреть разрешенные права, перейдите по ссылке https://oauth.
yandex.com/client/<client_id>/info, указав идентификатор приложения вместо <client_id>. Если параметры
\nscope
иoption_scope
не переданы, то токен будет выдан с правами, указанными при регистрации приложения.Пользователь решает, какие запрошенные дополнительные права предоставить. Токен будет выдан с правами, указанными в параметре
\nscope
, и правами, выбранными пользователем из списка, указанного в параметреoption_scope
.Этот параметр можно использовать, например, если приложению требуется электронная почта для регистрации пользователя, а доступ к портрету предпочтителен, но не обязателен.
\nПримечание. Все права доступа, запрошенные сразу через параметры
\n "}}">=<запрашиваемые дополнительные права>] [& \nscope
иoption_scope
, считаются необязательными.Указывает, что пользователь должен запросить разрешение на доступ к учетной записи (даже если пользователь уже разрешил доступ к этому приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ к приложению и выбрать учетную запись Яндекса.
\n \n Параметр обрабатывается, если его значение равно «да», «истина» или «1». Если установлено любое другое значение, параметр игнорируется.
\n "}}">=да] [&\nСтрока состояния, которую Яндекс. OAuth возвращается без изменений. Максимально допустимая длина строки составляет 1024 символа.
\nМожет использоваться, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.
\n "}}">=<произвольная строка>]
Параметр | .|
---|---|
client_id | Идентификатор приложения. Доступно в свойствах приложения (щелкните имя приложения, чтобы открыть его свойства). |
Расширенные параметры. Чтобы обеспечить уникальность, просто сгенерируйте UUID один раз и используйте его каждый раз, когда с этого устройства запрашивается новый токен. Идентификатор должен содержать от 6 до 50 символов. Допускаются только печатные символы ASCII (с кодами от 32 до 126). Ограничение. Приложение может иметь до 20 токенов, связанных с устройствами пользователя. Если Яндекс.OAuth выдает новый токен устройства для приложения, самый старый токен перестает работать. Дополнительные сведения о токенах для отдельных устройств см. в разделе Токен для устройства. | |
имя_устройства | Имя устройства для отображения пользователям. До 100 символов. Для мобильных устройств рекомендуется передавать имя устройства, указанное пользователем. Если имя отсутствует, его можно взять из модели устройства, названия и версии ОС и т. д. Если параметр Если параметр |
redirect_uri | URL-адрес для перенаправления пользователя после того, как он разрешит или запретит доступ к приложению. По умолчанию используется первый URI обратного вызова, указанный в настройках приложения (Платформы → Веб-сервисы → URI обратного вызова). Значение параметра может содержать только URL-адреса, указанные в настройках приложения. Если совпадение неточное, этот параметр игнорируется. |
login_hint | Явное указание учетной записи, для которой запрашивается токен. В значении параметра можно передать имя пользователя аккаунта Яндекса, а также адрес Яндекс.Почты или Яндекс.Почты для домена. Этот параметр позволяет помочь пользователю авторизоваться в Яндексе с той учетной записью, к которой приложению необходим доступ. Когда Яндекс.OAuth получает этот параметр, он проверяет авторизацию пользователя:
Если в этом параметре указан несуществующий аккаунт, Яндекс.OAuth сможет только сообщить об этом пользователю. Приложению придется снова запросить токен. |
область действия | Список прав доступа, которые в настоящее время требуются приложению, разделенные пробелом. Права необходимо запрашивать из списка, определенного при регистрации приложения. Чтобы посмотреть разрешенные права, перейдите по ссылке https://oauth.yandex.com/client/ Если параметры Этот параметр позволяет получить токен только с теми правами, которые в данный момент требуются приложению. Примечание. Все права доступа запрашиваются сразу через параметры |
option_scope | Список дополнительных прав доступа, разделенных пробелом, которые не требуются для работы приложения. Дополнительные права запрашиваются в дополнение к правам, указанным в Если параметры Пользователь решает, какие запрошенные дополнительные права предоставить. Токен будет выпущен с правами, указанными в Этот параметр можно использовать, например, если приложению требуется электронная почта для регистрации пользователя, а доступ к портрету предпочтителен, но не обязателен. Примечание. Все права доступа, запрошенные сразу через параметры |
принудительное_подтверждение | Указывает, что пользователь должен запросить разрешение на доступ к учетной записи (даже если пользователь уже разрешил доступ к этому приложению). Получив этот параметр, Яндекс.OAuth предложит пользователю разрешить доступ к приложению и выбрать учетную запись Яндекса. Параметр обрабатывается, если его значение равно «да», «истина» или «1». Если установлено любое другое значение, параметр игнорируется. |
состояние | Строка состояния, которую Яндекс. OAuth возвращается без изменений. Максимально допустимая длина строки составляет 1024 символа. Может использоваться, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен. |
Когда пользователь разрешает доступ к своим данным, Яндекс.OAuth перенаправляет его в приложение. Код подтверждения включен в URL-адрес перенаправления.
Примечание. Время жизни этого кода составляет 10 минут. По истечении этого времени код необходимо запрашивать снова.
Формат URL с кодом:
http://www. example.com/token? \nКод подтверждения, который можно обменять на токен OAuth.
\nВремя жизни этого кода 10 минут. По истечении этого времени код необходимо запрашивать снова.
\n "}}">=<код подтверждения> [&\nСтрока состояния, которую Яндекс. OAuth возвращается без изменений. Максимально допустимая длина строки составляет 1024 символа.
\nМожет использоваться, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.
\n "}}">=\nСтрока состояния, которую Яндекс. OAuth возвращается без изменений. Максимально допустимая длина строки составляет 1024 символа.
\nМожет использоваться, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.
\n "}}"> значение параметра в запросе>]
Параметр | Описание |
---|---|
код | Код подтверждения, который можно обменять на токен OAuth. Срок действия этого кода составляет 10 минут. По истечении этого времени код необходимо запрашивать снова. |
состояние | Строка состояния, которую Яндекс. OAuth возвращается без изменений. Максимально допустимая длина строки составляет 1024 символа. Может использоваться, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен. |
Если код подтверждения выдать не удалось, Яндекс.OAuth указывает код и описание ошибки в URL. Описание на языке домена OAuth, на который был отправлен запрос: например, для oauth.yandex.com
текст будет возвращен на английском языке.
Формат URL-адреса с информацией об ошибке:
http://www.example.com/token? error=<код ошибки> & error_description=<описание ошибки> [& state=<\nСтрока состояния, которую Яндекс. OAuth возвращается без изменений. Максимально допустимая длина строки составляет 1024 символа.
\nМожет использоваться, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен.
\n "}}"> значение параметра в запросе>]
Коды ошибок:
Приложение отправляет код, а также свой идентификатор и пароль в POST-запросе.
POST/токен HTTP/1.1 Хост: oauth.yandex.com Тип контента: application/x-www-form-urlencoded Длина содержимого:<
длина тела запроса>
[Авторизация: Basic<
закодированная строкаclient_id:client_secret
>
] \nМетод, используемый для запроса токена OAuth.
\nЕсли вы используете код подтверждения, укажите значение «authorization_code».
\n "}}">=код_авторизации & \nКод подтверждения получен от Яндекс.OAuth. Время жизни этого кода составляет 10 минут. По истечении этого времени код необходимо запрашивать снова.
\n "}}">=<код подтверждения> [& \nИдентификатор приложения. Доступно в свойствах приложения (щелкните имя приложения, чтобы открыть его свойства).
\nВы также можете передать пароль и идентификатор приложения в заголовке авторизации.
\n "}}">=<идентификатор приложения>] [& \nПароль приложения. Доступно в свойствах приложения (щелкните имя приложения, чтобы открыть его свойства).
\nВы также можете передать пароль и идентификатор приложения в заголовке авторизации.
\n "}}">=<пароль приложения>] [& \nИдентификатор устройства, для которого запрашивается токен.
\nЕсли ID был указан в параметре device_id при запросе кода подтверждения, параметры
\n "}}">=<идентификатор устройства>] [& \ndevice_id
иdevice_name
игнорируются при запросе токена.Имя устройства, для которого запрашивается токен.
\nЕсли при запросе кода подтверждения был передан параметр
\n "}}">=device_id
, параметрыdevice_id
иdevice_name
игнорируются при запросе токена.]
Parameter | Description |
---|---|
Required parameters | |
grant_type | The method used to запросить токен OAuth. Если вы используете код подтверждения, укажите значение «authorization_code». |
код | Код подтверждения получен от Яндекс.OAuth. Время жизни этого кода составляет 10 минут. По истечении этого времени код необходимо запрашивать снова. |
client_id Вы также можете передать пароль и идентификатор приложения в заголовке авторизации. | |
client_secret | Пароль приложения. Доступно в свойствах приложения (щелкните имя приложения, чтобы открыть его свойства). Вы также можете передать пароль и идентификатор приложения в заголовке авторизации. |
device_id | Идентификатор устройства, для которого запрашивается токен. Если ID был указан в параметре device_id при запросе кода подтверждения, 9Параметры 0204 device_id и |
имя_устройства | Имя устройства, для которого запрашивается токен. Если при запросе кода подтверждения был передан параметр |
Яндекс.OAuth возвращает токен OAuth, токен обновления и время их жизни в формате JSON:
200 ОК Тип содержимого: приложение/json { "token_type": "носитель", "access_token": "AQAAAAACy1C6ZAAAAfa6vDLuItEy8pg-iIpnDxIs", "expires_in": 124234123534, "refresh_token": "1:GN686QVt0mmakDd9:A4pYuW9LGk0_UnlrMIWklkAuJkUWbq27loFekJVmSYrdfzdePBy7:A-2dHOmBxiXgajnD-kYOwQ", "scope": "логин:информация логин:электронная почта логин:аватар" }
Свойство | Описание |
---|---|
token_type | Тип выпущенного токена. Всегда принимает значение «носитель». |
access_token | Токен OAuth с запрошенными правами или с правами, указанными при регистрации приложения. |
expires_in | Время жизни токена в секундах. |
refresh_token | Токен, который можно использовать для продления срока действия соответствующего токена OAuth. |
область действия | Права, запрашиваемые разработчиком или указанные при регистрации приложения. Поле области действия |
Время жизни токена обновления такое же, как и время жизни токена OAuth.
Если не удалось выдать токен, ответ содержит описание ошибки:
{ "error_description": "<описание ошибки>", "ошибка": "<код ошибки>" }
Коды ошибок:
author_pending
: Пользователь еще не ввел код подтверждения.bad_verification_code
: переданное значение параметраcode
не является 7-значным числом.invalid_client
: Приложение с указанным идентификатором (параметрclient_id
) не найдено или заблокировано. Этот код также возвращается, еслиПараметр client_secret
передал неверный пароль приложения.invalid_grant
: Недействительный или просроченный код подтверждения.invalid_request
: Неверный формат запроса (один из параметров не указан, указан дважды или не передан в теле запроса).invalid_scope
: Права приложения изменились после генерации кода подтверждения.неавторизованный_клиент
: Приложение отклонено на модерации или ожидает модерации.unsupported_grant_type
: Недопустимое значение параметраgrant_type
.Требуется базовая аутентификация
: Тип авторизации , указанный в заголовкеAuthorization
, не являетсяBasic
.
Структура ответа. Описание API
Внимание. Яндекс Коннект больше не поддерживается. API каталога будет закрыт с 01 марта 2023 г.
Для управления организациями, пользователями и доменами перейдите в Яндекс 360 для бизнеса.
Документация по API 360 (рус.)
Формат ответа General Directory API:
HTTP/1.1 <код состояния>Content-Type
— Формат данных тела ответа. Значение всегда должно бытьapplication/json; charset=utf-8
. "}}">: приложение/json; charset=utf-8WWW-Authenticate
(только для ответов 403) — Описание ошибки авторизации."}}">: <формат авторизации>Ссылка
— URL следующей и последней страницы в списке. Для запросов, содержащих список объектов."}}">:; rel="следующая", ; rel="last" X-Request-ID
— уникальный идентификатор ответа."}}">: <идентификатор ответа>…{json-object | json-array}
Code | Description |
---|---|
200 OK | Request with the |
201 Создано | В результате выполнения запроса методом |
204 Нет содержимого | Запрос с помощью метода |
400 Неверный запрос | Параметр запроса содержит недопустимое значение или формат данных. |
403 Запрещено | У пользователя или приложения нет разрешения на доступ к ресурсу, и запрос был отклонен. |
404 Не найдено | Запрошенный ресурс не найден. |
409 Конфликт | Запрос не может быть выполнен из-за конфликта имен. |
422 Необрабатываемый объект | Ошибка проверки. Запрос был отклонен. |
500 Внутренняя ошибка сервера | Служба обнаружила внутреннюю ошибку. Попробуйте повторно отправить запрос через несколько минут. |
503 Служба недоступна | Служба API временно недоступна. |
Ответы API каталога должны сопровождаться заголовками HTTP:
Content-Type
— Формат данных тела ответа. Значение всегда должно бытьapplication/json; кодировка=utf-8
.WWW-Authenticate
(только для ответов 403) — Описание ошибки авторизации.Ссылка
— адреса следующей и последней страницы в списке. Для запросов, содержащих список объектов.X-Request-ID
— Уникальный идентификатор ответа.
Некоторые ответы могут иметь дополнительные заголовки. Эти заголовки описаны в разделах, посвященных запросам API.
Тело ответа содержит данные в формате JSON. Вы можете найти описания поддерживаемых полей и структуры тела в разделах, посвященных запросам API.
Ответ на запрос второй страницы списка сотрудников:
Запрос выполнен успешно:
200 ОК
.Тело ответа в формате JSON:
Content-Type: application/json; кодировка=utf-8
.Ответ на запрос содержит несколько страниц:
HTTP/1.