Device token

Yandex.OAuth allows requesting a token for an application on a specific device. To do this, the token request or authorization code must specify the device ID and name (the device_id and device_name parameters described in the request parameters in this document). The user can see this name on the access management page in Passport. If only the ID is specified without the name, the token is marked as issued for an unknown device.

Restriction. An application can't have more than 20 tokens associated with devices for a specific user. If Yandex.OAuth successfully issues the application a new token for a device, the oldest token stops working.

Revoking a token on a specific device

Use a request to Yandex.OAuth to revoke a token issued for a specific device, for example, to guarantee logging out of an account.

To revoke a token, pass it to Yandex.OAuth with the application ID and password.

Application authentication

Requests to Yandex.OAuth should specify the ID and password that were generated during application registration.

There are various ways to pass them in the request:

In the Authorization header, base64-encoded in the <client_id>:<client_secret> string. In this case, specify the Basic authorization method.
Header example:
```
Authorization: Basic NDc2MDE4N2Q4MWJjNGI3Nzk5NDc2YjQycjUxMDM3MTM6ZjI1YmViZjk5MWZmNDE5ODkzZGIyNTU3MjhlNGUxZGU=
```
In the body of the POST request, in the client_id and client_secret parameters. These parameters must be passed at the same time.

If Yandex.OAuth receives the Authorization header, the client_id and client_secret parameters in the request body are ignored.

Request format

Send the request over the HTTPS protocol using the POST method.

Request format for revoking a token:

POST /revoke_token HTTP/1.1
Host: oauth.yandex.ru
Content-type: application/x-www-form-urlencoded
Content-Length: <length of the request body>
[Authorization: Basic <encoded client_id:client_secret string>]

   access_token=<token to revoke>
[& client_id=<application ID>]
[& client_secret=<application password>]


Parameter	Description
Required parameter
access_token	The OAuth token to revoke.
Additional parameters
client_id	Application ID. Available in the application properties (click the name of the application to open its properties). This parameter is required if the Authorization header was omitted in the request.
client_secret	Application password. Available in the application properties (click the name of the application to open its properties). This parameter is required if the Authorization header was omitted in the request.


Parameter	Description
Required parameter
access_token	The OAuth token to revoke.
Additional parameters
client_id	Application ID. Available in the application properties (click the name of the application to open its properties). This parameter is required if the Authorization header was omitted in the request.
client_secret	Application password. Available in the application properties (click the name of the application to open its properties). This parameter is required if the Authorization header was omitted in the request.

Response format

Yandex.OAuth returns the response in a JSON document.

A response is returned with the HTTP 200 code and the following body:

{
  "status": "ok"
}

If the request could not be executed, the response returns the HTTP error code and description:

{
  "error_description": "Client not found",
  "error": "invalid_client"
}


Key	Description
`error_description`	Human-readable error description.
`error`	Error code. The table below lists possible error codes.

Supported error codes


HTTP response code	Error code	Description
400	invalid_request	Invalid request format (omitted required parameter, and so on).
400	invalid_grant	The token that was passed does not belong to the specified app.
400 or 401	invalid_client	Returned in the following cases: The application with the specified ID was not found or is blocked. An invalid password was passed for the specified application ID. The HTTP 401 response code is returned if the application ID and password were passed in the `Authorization` header. Otherwise, the HTTP 400 code is returned.
400	unsupported_token_type	The token can't be revoked because the request for this token did not specify the device ID (the `device_id` parameter). If the token can't be revoked, you can delete it from local storage so the application loses access to the user's data.


HTTP response code	Error code	Description
400	invalid_request	Invalid request format (omitted required parameter, and so on).
400	invalid_grant	The token that was passed does not belong to the specified app.
400 or 401	invalid_client	Returned in the following cases: The application with the specified ID was not found or is blocked. An invalid password was passed for the specified application ID. The HTTP 401 response code is returned if the application ID and password were passed in the `Authorization` header. Otherwise, the HTTP 400 code is returned.
400	unsupported_token_type	The token can't be revoked because the request for this token did not specify the device ID (the `device_id` parameter). If the token can't be revoked, you can delete it from local storage so the application loses access to the user's data.