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

# Получение кода подтверждения от пользователя

Некоторые приложения (например, консольные) не могут [получить код подтверждения из URL](https://yandex.com.tr/dev/id/doc/ru/codes/code-url.md). В этом случае пользователь должен самостоятельно получить код от Яндекс OAuth и ввести его в приложении:

1. Чтобы пользователь подтвердил доступ к своим данным, настройте в приложении переход на страницу Яндекс OAuth. Для этого используйте [запрос для вывода кода подтверждения](#code).
  
   {% note tip %}

   Если на устройстве, где установлено приложение, недоступен браузер, пользователю придется перейти по нужному адресу на своем компьютере. Чтобы вводить адрес было удобнее, предоставьте пользователю QR-код или короткую ссылку.

   {% endnote %}

1. Код подтверждения [отобразится в браузере](#code-response). Для этого в свойстве приложения **Redirect URI** при [регистрации приложения](https://yandex.com.tr/dev/id/doc/ru/register-client.md#platforms) нужно указать адрес `https://oauth.yandex.ru/verification_code`.

1. Чтобы обменять код подтверждения на OAuth-токен, приложение должно отправить [POST-запрос](#token).

   <!-- source: ru/_includes/oauth/security.md -->
   Полученный токен можно сохранить в приложении и использовать для запросов к API до истечения [времени его жизни](https://yandex.com.tr/dev/id/doc/ru/concepts/ya-oauth-intro.md#ttl). Токен должен быть доступен только вашему приложению, поэтому не рекомендуется сохранять его в браузере или открытых конфигурационных файлах.
   <!-- endsource: ru/_includes/oauth/security.md -->

## Запрос кода подтверждения {#code}

### Формат запроса {#code-request}

<!-- source: ru/_includes/oauth/code-request.md -->
```
https://oauth.yandex.ru/authorize?response_type=code
 & client_id=<идентификатор приложения>
[& device_id=<идентификатор устройства>]
[& device_name=<имя устройства>]
[& redirect_uri=<адрес перенаправления>]
[& login_hint=<имя пользователя или электронный адрес>]
[& scope=<запрашиваемые необходимые права>]
[& optional_scope=<запрашиваемые опциональные права>]
[& force_confirm=yes]
[& state=<произвольная строка>]
[& code_challenge=<преобразованная верcия верификатора code_verifier>]
[& code_challenge_method=<метод преобразования>]
```

#### Обязательные параметры {#required}

#|
|| **Параметр** | **Описание** ||
|| `response_type` | Требуемый ответ. При запросе кода подтверждения следует указать значение <q>code</q>. ||
|| `client_id` | Идентификатор приложения. Доступен в [свойствах приложения](https://yandex.com.tr/dev/id/doc/ru/register-client.md#app-params). Чтобы открыть свойства, перейдите в [Яндекс OAuth](https://oauth.yandex.ru/) и нажмите на название приложения.
 ||
|#

#### Дополнительные параметры {#optional}
#|
|| **Параметр** | **Описание** ||
|| `device_id` | Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать [UUID](https://ru.wikipedia.org/wiki/UUID) и использовать его при каждом запросе нового токена с данного устройства.

Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые [ASCII](https://ru.wikipedia.org/wiki/ASCII)-символы (с кодами от 32 до 126).

Подробнее о работе с токенами для отдельных устройств читайте на странице [Отзыв токена для устройства](https://yandex.com.tr/dev/id/doc/ru/tokens/token-invalidate.md#device-token).

Если параметр `device_id` передан без параметра `device_name`, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства.

<!-- source: ru/_includes/oauth/concepts/device-token/id-device-token/limit.md -->
{% note alert %}

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

{% endnote %}
<!-- endsource: ru/_includes/oauth/concepts/device-token/id-device-token/limit.md -->
||
|| `device_name` | Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов.

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

Если параметр `device_name` передан без параметра `device_id`, он будет проигнорирован. Яндекс OAuth сможет выдать только обычный токен, не привязанный к устройству.
 ||
|| `redirect_uri` | URL, на который нужно перенаправить пользователя после того, как он разрешил приложению доступ. По умолчанию используется первый Redirect URI, указанный в настройках приложения (**Платформы** → **Веб-сервисы** → **Redirect URI**).

В значении параметра допустимо указывать только те адреса, которые перечислены в настройках приложения. Если совпадение неточное, параметр игнорируется. ||
|| `login_hint` | Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс Почты или Яндекс Почты для домена.

Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс OAuth проверяет авторизацию пользователя:

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

Если параметр указывает на несуществующий аккаунт, Яндекс OAuth сможет только сообщить об этом пользователю. Приложению придется запрашивать токен заново. ||
|| `scope` | Список прав доступа, необходимых приложению. Значения в списке разделяются пробелами.

Права должны запрашиваться из перечня, определенного при [регистрации приложения](https://yandex.com.tr/dev/id/doc/ru/register-client.md#access). Узнать допустимые права можно по ссылке [https://oauth.yandex.ru/client/<client_id>/info](https://oauth.yandex.ru/client/<client_id>/info), указав вместо <client_id> идентификатор приложения.

Если параметры `scope` и `optional_scope` не переданы, то токен будет выдан с правами, указанными при регистрации приложения.
||
|| `optional_scope` | Опциональные права запрашиваются в дополнение к правам, указанным в параметре `scope`.  

Права должны запрашиваться из перечня, определенного при [регистрации приложения](https://yandex.com.tr/dev/id/doc/ru/register-client.md#access). Узнать допустимые права можно по ссылке [https://oauth.yandex.ru/client/<client_id>/info](https://oauth.yandex.ru/client/<client_id>/info), указав вместо <client_id> идентификатор приложения.

Пользователь может выбрать, какие из опциональных прав предоставить. Токен будет выдан с правами, указанными в параметре `scope`, и правами, выбранными пользователем из указанных в параметре `optional_scope`.

Параметр можно использовать, например, если приложению нужна электронная почта для регистрации пользователя, а доступ к портрету желателен, но не обязателен.

{% note info %}

Права доступа, запрошенные одновременно через параметр `scope` и через параметр `optional_scope`, будут считаться опциональными.

{% endnote %}
 ||
|| `force_confirm` | Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса.

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

Параметр обрабатывается, если для него указано значение `yes`, `true` или `1`. При любом другом значении параметр игнорируется. ||
|| `state` | Строка состояния, которую Яндекс OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа. Можно использовать, например, для защиты от [CSRF-атак](https://ru.wikipedia.org/wiki/Межсайтовая_подделка_запроса) или идентификации пользователя, для которого запрашивается токен.
||
|| `code_challenge` | Версия верификатора `code_verifier`, преобразованная с помощью `code_challenge_method`. Применяется при использовании расширения PKCE для защиты передаваемых данных. Генерируется приложением для последующей проверки, что запрос токена поступает от того же приложения, которое запросило авторизацию. ||
|| `code_challenge_method` | Метод преобразования `code_verifier` в `code_challenge`. Возможные значения: `S256` (предпочтительное) и `plain` (для случаев, когда невозможно использовать S256). ||
|#
<!-- endsource: ru/_includes/oauth/code-request.md -->

### Формат ответа {#code-response}

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

![image](../_assets/code.png =500x)

<!-- source: ru/_includes/oauth/code-time.md -->
Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново.
<!-- endsource: ru/_includes/oauth/code-time.md -->

## Обмен кода подтверждения на OAuth-токен {#token}

### Формат запроса {#token-request}

<!-- source: ru/_includes/oauth/token-code-request.md -->
```
POST /token HTTP/1.1
Host: https://oauth.yandex.ru/
Content-type: application/x-www-form-urlencoded
Content-Length: <длина тела запроса>
[Authorization: Basic <закодированная методом base64 строка `client_id:client_secret`>]

   grant_type=authorization_code
 & code=<код подтверждения>
[& client_id=<идентификатор приложения>]
[& client_secret=<секретный ключ>]
[& device_id=<идентификатор устройства>]
[& device_name=<имя устройства>]
[& code_verifier=<верификатор>]
```

#### Обязательные параметры

#|
|| **Параметр** | **Описание** ||
|| `grant_type` | Способ запроса OAuth-токена.

Если вы используете код подтверждения, укажите значение `authorization_code`. ||
|| `code` | Код подтверждения, полученный от Яндекс OAuth.

Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново.
 ||
|#

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

#|
|| **Параметр** | **Описание** ||
|| `client_id` | Идентификатор приложения. Доступен в [свойствах приложения](https://yandex.com.tr/dev/id/doc/ru/register-client.md#app-params). Чтобы открыть свойства, перейдите в [Яндекс OAuth](https://oauth.yandex.ru/) и нажмите на название приложения.

Секретный ключ и идентификатор приложения также можно передать в [заголовке `Authorization`](#auth-header).
||
|| `client_secret` | Секретный ключ. Доступен в [свойствах приложения](https://yandex.com.tr/dev/id/doc/ru/register-client.md#app-params). Чтобы открыть свойства, перейдите в [Яндекс OAuth](https://oauth.yandex.ru/) и нажмите на название приложения.

Секретный ключ и идентификатор приложения также можно передать в [заголовке `Authorization`](#auth-header).

Если для защиты данных применяется расширение PKCE и в запросе передается параметр `code_verifier`, то секретный ключ передавать не требуется.||
|| `device_id` | Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать [UUID](https://ru.wikipedia.org/wiki/UUID) и использовать его при каждом запросе нового токена с данного устройства.

Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые [ASCII](https://ru.wikipedia.org/wiki/ASCII)-символы (с кодами от 32 до 126).

Подробнее о работе с токенами для отдельных устройств читайте на странице [Отзыв токена для устройства](https://yandex.com.tr/dev/id/doc/ru/tokens/token-invalidate.md#device-token).

Если параметр `device_id` передан без параметра `device_name`, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства.

<!-- source: ru/_includes/oauth/concepts/device-token/id-device-token/limit.md -->
{% note alert %}

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

{% endnote %}
<!-- endsource: ru/_includes/oauth/concepts/device-token/id-device-token/limit.md -->

||
|| `device_name` | Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов.

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

Если параметр `device_name` передан без параметра `device_id`, он будет проигнорирован. Яндекс OAuth сможет выдать только обычный токен, не привязанный к устройству.
 ||
|| `code_verifier` | Верификатор, обеспечивающий защиту передаваемых данных. Параметр применяется при использовании расширения PKCE. Представляет собой случайную строку, сгенерированную приложением, на основании которой формируется `code_challenge`. Сервер преобразует `code_verifier` методом `code_challenge_method`, полученным в [запросе на отправку кода подтверждения](https://yandex.com.tr/dev/id/doc/ru/codes/code-url.md#code), и сверяет результат с `code_challenge` из того же запроса.||
|#

<!-- source: ru/_includes/oauth/reference/auto-code-client/id-auto-code-client/auth-header.md -->
Параметры запроса должны передаваться в теле запроса и должны быть закодированы в urlencode.

{% note info %}

Чтобы передать идентификатор и секретный ключ в заголовке `Authorization`, закодируйте строку `<client_id>:<client_secret>` методом base64. 

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

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

### Формат ответа {#token-response}

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

- Запрос выполнен успешно

   Яндекс OAuth возвращает OAuth-токен, refresh-токен и время их жизни в JSON-формате:

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

  Параметры ответа:

   #|
   || **Свойство** | **Описание** ||
   || `token_type` | Тип выданного токена. Всегда принимает значение `bearer`.
 ||
   || `access_token` | OAuth-токен с правами, которые вы запросили или указали при [регистрации приложения](https://yandex.com.tr/dev/id/doc/ru/register-client.md#access).
 ||
   || `expires_in` | [Время жизни](https://yandex.com.tr/dev/id/doc/ru/concepts/ya-oauth-intro.md#ttl) токена в секундах. 
 ||
   || `refresh_token` | Токен, который можно использовать для [продления срока жизни](https://yandex.com.tr/dev/id/doc/ru/tokens/refresh-client.md ) соответствующего OAuth-токена. [Время жизни](https://yandex.com.tr/dev/id/doc/ru/concepts/ya-oauth-intro.md#ttl) refresh-токена совпадает с временем жизни OAuth-токена.||
   || `scope` | Права, запрошенные разработчиком или указанные при [регистрации приложения](https://yandex.com.tr/dev/id/doc/ru/register-client.md#access). Поле `scope` является дополнительным и возвращается, если OAuth предоставил токен с меньшим набором прав, чем было запрошено. ||
   |#

- Запрос выполнен с ошибкой

   Если выдать токен не удалось, ответ содержит описание ошибки:

   ```json
   {
      "error_description": "<описание ошибки>",
      "error": "<код ошибки>"
   }
   ```

   Возможные коды ошибок:

   * `authorization_pending` — пользователь еще не ввел код подтверждения.
   
   * `bad_verification_code` — переданное значение параметра `code` не является 7-значным числом.
   
   * <!-- source: ru/_includes/oauth/errors/invalid-client.md -->
     `invalid_client` ― приложение с указанным идентификатором (параметр `client_id`) не найдено или заблокировано. Этот код также возвращается, если в параметре `client_secret` передан неверный секретный ключ.
     <!-- endsource: ru/_includes/oauth/errors/invalid-client.md -->
   
   * `invalid_grant` — неверный или просроченный код подтверждения.
   
   * <!-- source: ru/_includes/oauth/errors/invalid-request.md -->
     `invalid_request` ― неверный формат запроса (один из параметров не указан, указан дважды, или передан не в теле запроса).
     <!-- endsource: ru/_includes/oauth/errors/invalid-request.md -->
   
   * `invalid_scope` — права приложения изменились после генерации кода подтверждения.
   
   * <!-- source: ru/_includes/oauth/errors/unauthorized-client.md -->
     `unauthorized_client` — приложение было отклонено при модерации или только ожидает ее. Также возвращается, если приложение заблокировано.
     <!-- endsource: ru/_includes/oauth/errors/unauthorized-client.md -->
   
   * <!-- source: ru/_includes/oauth/errors/grant-type.md -->
     `unsupported_grant_type` ― недопустимое значение параметра `grant_type`.
     <!-- endsource: ru/_includes/oauth/errors/grant-type.md -->
   
   * <!-- source: ru/_includes/oauth/errors/basic-auth.md -->
     `Basic auth required` — тип авторизации, указанный в заголовке `Authorization`, отличен от <q>Basic</q>.
     <!-- endsource: ru/_includes/oauth/errors/basic-auth.md -->
   
   * <!-- source: ru/_includes/oauth/errors/mailformed.md -->
     `Malformed Authorization header` — заголовок `Authorization` не соответствует формату `<client_id>:<client_secret>`, или эта строка не закодирована методом base64.
     <!-- endsource: ru/_includes/oauth/errors/mailformed.md -->

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