Getting a confirmation code from a URL

Set redirection to the Yandex OAuth page in the app so that the user confirms access to their data. To do this, use the request for getting the confirmation code from URL.

When the user grants access to their data, Yandex OAuth redirects them to the app to the URL specified in the Redirect URI field when registering the app.
The confirmation code is included in the redirect URL. To switch the confirmation code for the OAuth token, the app must send a POST request.

The received token can be saved in the app and used for requests until its lifetime expires. The token should only be available to your app, so we don't recommend saving it in the browser or open configuration files.

For enhanced protection when transmitting data, you can use parameters supported by the PKCE extension of the OAuth 2.0 protocol in your requests: an arbitrary code_verifier string, its transformed version code_challenge, and information about the transformation method — code_challenge_method.

Confirmation code request

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`	Expected response. When you request the confirmation code, specify the code value.
`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.
`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 (Platforms → Web services → Redirect URI) app settings is used. The parameter value can only contain URLs listed in the app settings. If the match isn't exact, this parameter is ignored.
`login_hint`	Explicit indication of the account the token is requested for. The Yandex account username and the Yandex Mail or Yandex Mail for Domain address can be passed in the parameter value. This parameter allows you to help the user log in to Yandex with the account that the app needs access to. When Yandex OAuth receives this parameter, it checks the user's authorization: If the user is already logged in with the desired account, Yandex OAuth asks for access permission. If the user isn't logged in with the appropriate account, they see the Yandex login form where the login field is filled in with the parameter value. Remember that the token won't necessarily be requested for the specified account: the user can erase the pre-filled username and log in with any other. If this parameter indicates a nonexistent account, Yandex OAuth will only be able to inform the user. The app will have to request the token again.
`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 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 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. 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 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.
`force_confirm`	Indicates that the user must request permission to access the account (even if the user already allowed access to this app). After receiving this parameter, Yandex OAuth will prompt the user to allow access to the app and choose the Yandex account. This parameter is needed, for example, if the user logged in to the website under one Yandex account, and wants to switch to another one. If the parameter isn't used, the user will explicitly have to switch accounts in a Yandex service or revoke the token issued to the website. The parameter is processed if its value is `yes`, `true`, or `1`. In case of any other value, 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

Request successfully completed

Request completed with an error

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

http://www.example.com/token?code=<confirmation code>
[& state=<"state" value from the request>]

Response parameters:

Property

Description

code

Confirmation code that can be exchanged for an OAuth token.

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

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.

If the confirmation code couldn't be issued, Yandex OAuth specifies the error code and description in the URL.

http://www.example.com/token?error=<error code>
 & error_description=<error description>
[& state=<"state" value from the request>]

Error codes:

unauthorized_client: The app was rejected during moderation or is awaiting moderation. Also returned if the app is blocked.

Exchanging a 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, specify the authorization_code value.

code

Confirmation code from Yandex OAuth.

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. The secret key and app ID can also be passed 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. 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 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.
`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 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.

Response format

Request successfully completed

Request completed with an error

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 permissions you requested or specified when registering your 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`	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 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.
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.

Was the article helpful?

Alternative method with a confirmation code

Receiving a confirmation code from the user