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

Токен для устройства

Яндекс.OAuth позволяет запросить токен для приложения на конкретном устройстве. Для этого в запросе токена или кода подтверждения следует указать идентификатор устройства и его имя (параметры device_id и device_name описаны в форматах запросов на страницах этого документа). Это имя пользователь сможет увидеть на странице управления доступом в Паспорте. Если указать только идентификатор, без имени, токен будет помечен как выданный для неизвестного устройства.

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

Отзыв токена на определенном устройстве

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

Чтобы отозвать токен, нужно передать его в Яндекс.OAuth с идентификатором и паролем приложения.

Аутентификация приложения

В запросах к Яндекс.OAuth следует указывать идентификатор и пароль, которые были сгенерированы при регистрации приложения.

В запросе их можно передать разными способами:

  • В заголовке Authorization, в строке <client_id>:<client_secret>, закодированной методом base64. При этом следует указывать базовый (Basic) метод авторизации.

    Пример заголовка:

    Authorization: Basic NDc2MDE4N2Q4MWJjNGI3Nzk5NDc2YjQycjUxMDM3MTM6ZjI1YmViZjk5MWZmNDE5ODkzZGIyNTU3MjhlNGUxZGU=
  • В теле POST-запроса, в параметрах client_id и client_secret. Эти параметры обязательно должны передаваться одновременно.

Если Яндекс.OAuth получает заголовок Authorization, параметры client_id и client_secret в теле запроса игнорируются.

Формат запроса

Запрос следует отправлять по протоколу HTTPS c помощью метода POST.

Формат запроса для отзыва токена:

POST /revoke_token HTTP/1.1
Host: oauth.yandex.ru
Content-type: application/x-www-form-urlencoded
Content-Length: <длина тела запроса>
[Authorization: Basic <закодированная строка client_id:client_secret>]

   access_token
[no-highlight[

OAuth-токен, который нужно отозвать.

]no-highlight]
=<отзываемый токен> [& client_id
[no-highlight[

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

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

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

Параметр обязателен, если в запросе не был указан заголовок Authorization.

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

access_token

OAuth-токен, который нужно отозвать.

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

client_id

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

client_secret

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

Параметр обязателен, если в запросе не был указан заголовок Authorization.

Формат ответа

Яндекс.OAuth возвращает ответ в JSON-документе.

Возвращается ответ с HTTP-кодом 200 и следующим телом:

{
  "status": "ok"
}

Если запрос выполнить не удалось, то ответ возвращается с HTTP-кодом ошибки и ее описанием:

{
  "error_description
[no-highlight[

Описание ошибки на естественном языке.

]no-highlight]
": "Client not found", "error
[no-highlight[

Код ошибки. Список возможных кодов приведен в таблице ниже.

]no-highlight]
": "invalid_client" }
КлючОписание
error_description Описание ошибки на естественном языке.
error Код ошибки. Список возможных кодов приведен в таблице ниже.

Поддерживаемые коды ошибок

HTTP-код ответаКод ошибкиОписание
400invalid_request

Неверный формат запроса (не указан обязательный параметр и т. п.).

400invalid_grant

Переданный токен не принадлежит указанному приложению.

400 или 401

invalid_client

Возвращается в следующих случаях:

  • Приложение с указанным идентификатором не найдено или заблокировано.

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

HTTP-код ответа 401 возвращается, если идентификатор и пароль приложения были переданы в заголовке Authorization. В противном случае возвращается HTTP-код 400.

400unsupported_token_type

Токен не может быть отозван, так как при запросе этого токена не был указан идентификатор устройства (параметр device_id).

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