Entering the code on the authorization page Yandex OAuth

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

  1. Set up requests for two codes in the app: device_code for the device and user_code for the user, so that the user confirms access to their data. To do this, use the confirmation code request.

    The lifetime of this code is 10 minutes. After this time, the code must be requested again.

  2. After receiving the codes, the app:

  3. If the code is entered correctly, Yandex OAuth suggests granting or denying access for the app. Yandex OAuth returns the token in response to the next app request.

Requesting confirmation codes

Request format

The app must 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 rights>]
[& optional_scope=<requested optional rights>]

Required parameters

Parameter

Description

client_id

Application ID. Available in the app properties. To open properties, go to Yandex OAuth and click the app name.

Advanced 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 Revoking a token for a specific 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

List of the access rights the app requires. Values in the list are separated by commas.

Rights must be requested from the list defined when registering the app. To view the allowed rights, go to https://oauth.yandex.com/client/<client_id>/info and specify the app ID instead of <client_id>.

If the scope and optional_scope parameters aren't passed, the token will be issued with the rights specified when registering the application.

optional_scope

Optional rights are requested in addition to the rights specified in the scope parameter.

Rights must be requested from the list defined when registering the app. To view the allowed rights, go to https://oauth.yandex.com/client/<client_id>/info and specify the app ID instead of <client_id>.

The user decides which requested optional rights to grant. The token will be issued with the rights specified in the scope parameter, and the rights selected by the user from the list specified in the optional_scope parameter.

This parameter can be used, for example, if the app needs an email to register the user, and access to the portrait is preferred, but not required.

Note

All access rights requested at once via the scope and optional_scope parameters are considered optional.

Response format

Yandex OAuth returns the code for the user and the information for the token request:

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 to request an OAuth token.

user_code

The code the user should enter to allow access to their data.

verification_url

URL of the page where the user should enter the code from the user_code: https://oauth.yandex.com/device property.

interval

The minimum interval with which the app must request an OAuth token. If requests come more often, Yandex OAuth may respond with an error.

expires_in

Code pair lifetime. After this period, a token for them can't be received and the procedure needs to be started again.

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

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

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.

Exchanging a confirmation code for an OAuth token

Request format

The app sends the device code as well as its ID and password 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, enter the device_code value.

code

Code from the device_code parameter received when requesting verification codes.

The lifetime of this code is 10 minutes. After this time, the code must be requested again.

Advanced parameters

Parameter

Description

client_id

Application ID. Available in the app properties. To open properties, go to Yandex OAuth and click the app name.

You can also pass the password and app ID in the Authorization header.

client_secret

Secret key. Available in the app properties. To open properties, go to Yandex OAuth and click the app name.

You can also pass the password and app ID in the Authorization header.

Note

To pass the ID and the secret key in the Authorization header, encode the <client_id>:<client_secret> string using the base64 method.

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

Response format

Yandex OAuth returns the OAuth token, 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 the OAuth token lifetime.

scope

The rights requested by the developer or specified when registering the app. The scope field is optional and is returned if OAuth provided a token with a smaller set of rights than requested.

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

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

Error codes:

  • authorization_pending: The user didn't enter the confirmation code yet.

  • bad_verification_code: The passed code parameter 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: The app rights 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.

Previous
Receiving a confirmation code from the user
Next
Authorization page design
In this article: