Get a confirmation code from the user

Some apps (such as console apps) can't get a confirmation code from a URL. In this case, the user should get the code from Yandex OAuth and enter it in the app.

For the user to confirm granting access to their data, configure your app to redirect them to the Yandex OAuth page. To do this, use a request for displaying the confirmation code.

Tip

If no browser is available on the device where the app is installed, the user will have to visit the needed address on their computer. To make entering the address easier, provide users with a QR code or a short link.
The confirmation code is displayed in the browser. To achieve that, specify the address https://oauth.yandex.com/verification_code in the Redirect URI field when registering the app.
To exchange the confirmation code for an OAuth token, the app has to send a POST request.

The obtained token can be saved in the app and used for API requests until its lifetime ends. Only your app should have access to the token, so avoid saving it in the browser or public configuration files.

Request a confirmation code

Request format

https://oauth.yandex.com/authorize?response_type=code
 & client_id=<app ID>
[& device_id=<device ID>]
[& device_name=<device name>]
[& redirect_uri=<redirect URL>]
[& login_hint=<username or email address>]
[& scope=<requested required permissions>]
[& optional_scope=<requested optional permissions>]
[& force_confirm=yes]
[& state=<arbitrary string>]
[& code_challenge=<transformed version of code_verifier>]
[& code_challenge_method=<transformation method>]

Required parameters

Parameter	Description
`response_type`	The required response. Should be set to code when requesting a confirmation code.
`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.
`redirect_uri`	A URL to redirect the user to after they grant access to the app. By default, the first Redirect URI specified in the app settings is used (Platforms → Web services → Redirect URI). Only the addresses listed in the app settings can be included in this parameter's value. The parameter is ignored when the URLs don't match exactly.
`login_hint`	A string that explicitly points to the account for which a token is requested. A Yandex account username, Yandex Mail address, or Yandex Mail for Domain address can be passed in the parameter value. This parameter helps the user to log in to the Yandex account that your app needs access to. When Yandex OAuth receives this parameter, it checks the user's login status: If the user is already logged in to the right account, Yandex OAuth simply asks for access. If the user isn't logged in to the right account, a Yandex login form is displayed. The username field is populated with the parameter value. Keep in mind that the token won't necessarily be requested for the specified account. The user might delete the auto-populated username and log in with any other. When this parameter points to a nonexistent account, Yandex OAuth can only inform the user about it. The app will have to request a token again.
`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.
`force_confirm`	The flag indicating whether permission to access the user's account should be requested every time (even when the user has already granted access for this app). After receiving this parameter, Yandex OAuth prompts the user to grant the app access and select a Yandex account. This parameter can come in handy when, for example, the user is logged in to your website with a specific Yandex account and wants to switch to a different one. If you don't use this parameter, the user will have to explicitly switch accounts in a Yandex service or revoke the token issued for the website. The parameter is processed if its value is `yes`, `true`, or `1`. If any other value is set, the parameter is ignored.
`state`	The status bar that Yandex OAuth returns without changes. The maximum allowed string length is 1024 characters. Can be used, for example, to protect against CSRF attacks or identify the user the token is requested for.
`code_challenge`	The `code_verifier` version transformed using the `code_challenge_method`. It's meant for cases when working with the PKCE extension for protecting transmitted data. The code challenge is generated by the app so that later it can be verified that the request for a token is coming from the same app as the request for an authorization code.
`code_challenge_method`	The method of transforming the `code_verifier` into a `code_challenge`. Possible values: `S256` (preferred) and `plain` (for cases where S256 can't be used).

Response format

When the user grants access to their data, Yandex OAuth displays the confirmation code:

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

Exchange the confirmation code for an OAuth token

Request format

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

   grant_type=authorization_code
 & code=<confirmation code>
[& client_id=<app ID>]
[& client_secret=<secret key>]
[& device_id=<device ID>]
[& device_name=<device name>]
[& code_verifier=<verifier>]

Required parameters

Parameter

Description

grant_type

The method used to request the OAuth token.

If you use a confirmation code, set the value to authorization_code.

code

Confirmation code from Yandex OAuth.

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. If the PKCE extension is used for data protection and the `code_verifier` parameter is passed in the request, you don't need to pass the secret key.
`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.
`code_verifier`	The verifier ensuring that transmitted data is protected. This parameter is used when working with the PKCE protocol extension. It's an arbitrary string generated by the app. `code_challenge` is formed based on this string. The server transforms the `code_verifier` using the `code_challenge_method` received in the request for a confirmation code and compares the result with the `code_challenge` from the same request.

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 a URL

Enter the code on the Yandex OAuth authorization page