Enter the code on the Yandex OAuth authorization page

On some devices (such as TVs), entering a confirmation code in the app may be difficult. In this case, you can ask the user to enter the code on the Yandex OAuth authorization page:

For the user to confirm granting access to their data, configure your app to request two codes: a device_code and a user_code. To do this, use a request for confirmation codes.

The code's lifetime is 10 minutes. When it expires, you need to request a new code.
After receiving the codes, the app simultaneously:
- Prompts the user to enter the user_code on the Device authorization page.
- Starts requesting an OAuth token periodically, passing the device_code.
If the code is entered correctly, Yandex OAuth prompts the user to grant or deny access for the app. Yandex OAuth returns a token in response to the next app request.

Request confirmation codes

Request format

The app has to request confirmation codes using the HTTP POST method:

POST /device/code
Host: https://oauth.yandex.com/

 & client_id=<app ID>
[& device_id=<device ID>]
[& device_name=<device name>]
[& scope=<requested required permissions>]
[& optional_scope=<requested optional permissions>]

Required parameters

Parameter	Description
`client_id`	The app ID. It can be found in the app properties. To open them, go to Yandex OAuth and select the app name.

Optional parameters

Parameter	Description
`device_id`	Unique ID of the device the token is requested for. To ensure uniqueness, just generate a UUID once and use it every time a new token is requested from this device. The ID must be from 6 to 50 characters long. Only printable ASCII characters are allowed (with codes from 32 to 126). Learn more about tokens for individual devices on the Revoke a token for a device page. If the `device_id` parameter is sent without the `device_name` parameter, the token is marked as issued for an unknown device in the user interface. Alert An app can have up to 30 tokens linked to a user's devices. If Yandex OAuth issues a new device token for the app, the oldest token stops working.
`device_name`	The name of the device to show users. Up to 100 characters. For mobile devices, we recommend passing the device name specified by the user. If a name is missing, the name can be taken from the device model, OS name and version, and so on. If the `device_name` parameter is sent without the `device_id` parameter, it is ignored. Yandex OAuth can only issue a regular token that is not linked to a device.
`scope`	A list of permissions that the app needs. Values in the list are space-separated. You should only request permissions from the list defined at the time of app registration. To see the allowed permissions, open the link https://oauth.yandex.com/client/<client_id>/info, replacing <client_id> with your app's ID. If the `scope` and `optional_scope` parameters aren't passed, the token is issued with the permissions set during app registration.
`optional_scope`	Optional permissions are requested in addition to those specified in the `scope` parameter. You should only request permissions from the list defined at the time of app registration. To see the allowed permissions, open the link https://oauth.yandex.com/client/<client_id>/info, replacing <client_id> with your app's ID. The user can choose which optional permissions to grant. The token is issued with the permissions set in the `scope` parameter and the permissions selected by the user from the `optional_scope` list. This parameter can be used, for example, when the app needs the user's email address to register them, while access to the avatar is good to have but not required. Note Permissions included both in `scope` and `optional_scope` are considered optional.

Response format

Successful request

Request resulted in an error

Yandex OAuth returns a user code and information for requesting a token:

200 OK

Content-type: application/json

{
   "device_code": "3e2a5a5c0e02439aa78a23442721848c",
   "user_code": "h5nbcr6c",
   "verification_url": "https://oauth.yandex.com/device",
   "interval": 5,
   "expires_in": 300
}

Response parameters:

Property	Description
`device_code`	The code that should be used to request an OAuth token.
`user_code`	The code that the user should enter to grant access to their data.
`verification_url`	The address of the page where the user should enter the `user_code`: `https://oauth.yandex.com/device`.
`interval`	The minimum interval between requests for an OAuth token, in seconds. If requests are more frequent, Yandex OAuth may respond with an error.
`expires_in`	The validity period of the code pair, in seconds. When it ends, the codes can no longer be used to obtain a token, and the process has to be started again.

If a token couldn't be issued, the response contains an error description:

{
   "error_description": "<error message>",
   "error": "<error code>"
}

Possible error codes:

invalid_client: The app with the specified ID (the client_id parameter) wasn't found or is blocked. This code is also returned if the client_secret parameter passed an invalid app password.
invalid_request: Invalid request format (one of the parameters isn't specified, specified twice, or isn't passed in the request body).
unauthorized_client: The app was rejected during moderation or is awaiting moderation. Also returned if the app is blocked.
Basic auth required: The authorization type specified in the Authorization header is not Basic.
Malformed Authorization header: The Authorization header isn't in <client_id>:<client_secret> format, or this string isn't Base64-encoded.

Exchange the confirmation code for an OAuth token

Request format

The app sends its ID, secret key, and the device code in a POST request.

POST /token HTTP/1.1
Host: https://oauth.yandex.com/
Content-type: application/x-www-form-urlencoded
Content-Length: <request body length>
[Authorization: Basic <encoded string `client_id:client_secret`>]

   grant_type=device_code
 & code=<device code>
[& client_id=<app ID>]
[& client_secret=<secret key>]

Required parameters

Parameter

Description

grant_type

The method used to request the OAuth token.

If you use a confirmation code for the device, set the device_code value.

code

The code from the device_code parameter received when requesting confirmation codes.

The code's lifetime is 10 minutes. When it expires, you need to request a new code.

Optional parameters

Parameter

Description

client_id

The app ID. It can be found in the app properties. To open them, go to Yandex OAuth and select the app name.

The secret key and app ID can also be passed in the Authorization header.

client_secret

The secret key. It can be found in the app properties. To open them, go to Yandex OAuth and select the app name.

The secret key and app ID can also be passed in the Authorization header.

Request parameters must be passed in the request body and must be URL-encoded.

Note

To pass the app ID and secret key in the Authorization header, encode the string <client_id>:<client_secret> with Base64.

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

Response format

Successful request

Request resulted in an error

Yandex OAuth returns an OAuth token, a refresh token, and their lifetime in JSON format:

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"
}

Response parameters:

Property	Description
`token_type`	Type of token issued. Always takes the `bearer` value.
`access_token`	An OAuth token with the requested rights or with the rights specified when registering the app.
`expires_in`	Token lifetime in seconds.
`refresh_token`	A token that can be used to extend the lifetime of the corresponding OAuth token. The lifetime of the refresh token is the same as that of the OAuth token.
`scope`	Permissions requested by the developer or specified during app registration. The `scope` field is optional and is returned if OAuth provided a token with fewer permissions than was requested.

If a token couldn't be issued, the response contains an error description:

{
   "error_description": "<error message>",
   "error": "<error code>"
}

Possible error codes:

authorization_pending — User hasn't entered the confirmation code yet.
bad_verification_code — The passed code value isn't a 7-digit number.
invalid_client: The app with the specified ID (the client_id parameter) wasn't found or is blocked. This code is also returned if the client_secret parameter passed an invalid app password.
invalid_grant — Invalid or expired confirmation code.
invalid_request: Invalid request format (one of the parameters isn't specified, specified twice, or isn't passed in the request body).
invalid_scope — App permissions changed after the confirmation code was generated.
unauthorized_client: The app was rejected during moderation or is awaiting moderation. Also returned if the app is blocked.
unsupported_grant_type: Invalid grant_type parameter value.
Basic auth required: The authorization type specified in the Authorization header is not Basic.
Malformed Authorization header: The Authorization header isn't in <client_id>:<client_secret> format, or this string isn't Base64-encoded.

Was the article helpful?

Get a confirmation code from the user

Step 3. Get user information