---
metadata:
  - name: generator
    content: Diplodoc Platform v5.44.0
alternate:
  - https://yandex.ru/dev/id/doc/en/codes/screen-code-oauth.md
  - https://yandex.ru/dev/id/doc/ru/codes/screen-code-oauth.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/id/doc/en/llms.txt

# 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](#code). 

   <!-- source: en/_includes/oauth/code-time.md -->
   The lifetime of this code is 10 minutes. After this time, the code must be requested again.
   <!-- endsource: en/_includes/oauth/code-time.md -->

1. After [receiving the codes](#code-response), the app:

   * Prompts the user to enter `user_code` on the [Device authorization](https://oauth.yandex.com/device) page.

   * Starts [requesting an OAuth token](#token) periodically, passing the `device_code`.

1. 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 {#code}

### Request format {#code-request}

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 permissions>]
[& optional_scope=<requested optional permissions>]
```

#### Required parameters

#|
|| **Parameter** | **Description** ||
|| `client_id` | Application ID. Available in the [app properties](https://yandex.ru/dev/id/doc/en/register-client.md#app-params). To open properties, go to [Yandex OAuth](https://oauth.yandex.com/) and click the app name.
 ||
|#

#### Advanced parameters
#|
|| **Parameter** | **Description** ||
|| `device_id` | 
<!-- source: en/_includes/oauth/api-params/device-id.md -->
Unique ID of the device the token is requested for. To ensure uniqueness, just generate a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) 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](https://en.wikipedia.org/wiki/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](https://yandex.ru/dev/id/doc/en/tokens/token-invalidate.md#device-token) 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.
<!-- endsource: en/_includes/oauth/api-params/device-id.md -->

<!-- source: en/_includes/oauth/concepts/device-token/id-device-token/limit.md -->
{% note 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.

{% endnote %}
<!-- endsource: en/_includes/oauth/concepts/device-token/id-device-token/limit.md -->
||
|| `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](https://yandex.ru/dev/id/doc/en/register-client.md#access). To see the allowed permissions, open the link [https://oauth.yandex.com/client/<client_id>/info](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 will be issued with the rights specified when registering the application.
 ||
|| `optional_scope` | Optional permissions are requested in addition to those specified in the `scope` parameter.  

Rights must be requested from the list defined when [registering the app](https://yandex.ru/dev/id/doc/en/register-client.md#access). To see the allowed permissions, open the link [https://oauth.yandex.com/client/<client_id>/info](https://oauth.yandex.com/client/<client_id>/info), replacing <client_id> with your app's 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 info %}

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

{% endnote %}
 ||
|#

### Response format {#code-response}

{% list tabs %}

- Request successfully completed

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

   ```json
   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](#token-request). ||
   || `user_code` | The code the user should enter to allow 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 come more often, Yandex OAuth may respond with an error. ||
   || `expires_in` | The validity period of the code pair, in seconds. After this period, a token for them can't be received and the procedure needs to be started again. ||
   |#

- Request completed with an error

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

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

   Error codes:

    * <!-- source: en/_includes/oauth/errors/invalid-client.md -->
      `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.
      <!-- endsource: en/_includes/oauth/errors/invalid-client.md -->
   
    * <!-- source: en/_includes/oauth/errors/invalid-request.md -->
      `invalid_request`: Invalid request format (one of the parameters isn't specified, specified twice, or isn't passed in the request body).
      <!-- endsource: en/_includes/oauth/errors/invalid-request.md -->

    * <!-- source: en/_includes/oauth/errors/unauthorized-client.md -->
      `unauthorized_client`: The app was rejected during moderation or is awaiting moderation. Also returned if the app is blocked.
      <!-- endsource: en/_includes/oauth/errors/unauthorized-client.md -->
   
    * <!-- source: en/_includes/oauth/errors/basic-auth.md -->
      `Basic auth required`: The authorization type specified in the `Authorization` header is not <q>Basic</q>.
      <!-- endsource: en/_includes/oauth/errors/basic-auth.md -->

    * <!-- source: en/_includes/oauth/errors/mailformed.md -->
      `Malformed Authorization header`: The `Authorization` header isn't in `<client_id>:<client_secret>` format, or this string isn't Base64-encoded.
      <!-- endsource: en/_includes/oauth/errors/mailformed.md -->

{% endlist %}

## Exchanging a confirmation code for an OAuth token {#token}

### Request format {#token-request}

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` | The code from the `device_code` parameter received when [requesting confirmation codes](#code-response).

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](https://yandex.ru/dev/id/doc/en/register-client.md#app-params). To open properties, go to [Yandex OAuth](https://oauth.yandex.com/) and click the app name. 

The secret key and app ID can also be passed in the [`Authorization` header](#auth-header).
||
|| `client_secret` | Secret key. Available in the [app properties](https://yandex.ru/dev/id/doc/en/register-client.md#app-params). To open properties, go to [Yandex OAuth](https://oauth.yandex.com/) and click the app name.

The secret key and app ID can also be passed in the [`Authorization` header](#auth-header).
 ||
|#

<!-- source: en/_includes/oauth/reference/auto-code-client/id-auto-code-client/auth-header.md -->
Request parameters must be passed in the request body and must be URL-encoded.

{% note info %}

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, while the `client_id` and `client_secret` parameters in the request body are ignored. {#auth-header}

{% endnote %}
<!-- endsource: en/_includes/oauth/reference/auto-code-client/id-auto-code-client/auth-header.md -->

### Response format {#token-response}

<!-- source: en/_includes/oauth/token-code-response.md -->
{% list tabs %}

- Request successfully completed

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

   ```json
   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 permissions you requested or specified when [registering your app](https://yandex.ru/dev/id/doc/en/register-client.md#access).
 ||
   || `expires_in` | [Token lifetime](https://yandex.ru/dev/id/doc/en/concepts/ya-oauth-intro.md#ttl) in seconds. 
 ||
   || `refresh_token` | A token that can be used to [extend the lifetime](https://yandex.ru/dev/id/doc/en/tokens/refresh-client.md) of the corresponding OAuth token. [The lifetime](https://yandex.ru/dev/id/doc/en/concepts/ya-oauth-intro.md#ttl) of the refresh token is the same as the OAuth token lifetime.||
   || `scope` | Rights requested by the developer or specified when [registering the app](https://yandex.ru/dev/id/doc/en/register-client.md#access). The `scope` field is optional and is returned if OAuth provided a token with a smaller set of rights than requested. ||
   |#

- Request completed with an error

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

   ```json
   {
      "error_description": "<error message>",
      "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.
   
   * <!-- source: en/_includes/oauth/errors/invalid-client.md -->
     `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.
     <!-- endsource: en/_includes/oauth/errors/invalid-client.md -->
   
   * `invalid_grant` — Invalid or expired confirmation code.
   
   * <!-- source: en/_includes/oauth/errors/invalid-request.md -->
     `invalid_request`: Invalid request format (one of the parameters isn't specified, specified twice, or isn't passed in the request body).
     <!-- endsource: en/_includes/oauth/errors/invalid-request.md -->
   
   * `invalid_scope`: The app rights changed after the confirmation code was generated.
   
   * <!-- source: en/_includes/oauth/errors/unauthorized-client.md -->
     `unauthorized_client`: The app was rejected during moderation or is awaiting moderation. Also returned if the app is blocked.
     <!-- endsource: en/_includes/oauth/errors/unauthorized-client.md -->
   
   * <!-- source: en/_includes/oauth/errors/grant-type.md -->
     `unsupported_grant_type`: Invalid `grant_type` parameter value.
     <!-- endsource: en/_includes/oauth/errors/grant-type.md -->
   
   * <!-- source: en/_includes/oauth/errors/basic-auth.md -->
     `Basic auth required`: The authorization type specified in the `Authorization` header is not <q>Basic</q>.
     <!-- endsource: en/_includes/oauth/errors/basic-auth.md -->
   
   * <!-- source: en/_includes/oauth/errors/mailformed.md -->
     `Malformed Authorization header`: The `Authorization` header isn't in `<client_id>:<client_secret>` format, or this string isn't Base64-encoded.
     <!-- endsource: en/_includes/oauth/errors/mailformed.md -->

{% endlist %}
<!-- endsource: en/_includes/oauth/token-code-response.md -->