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.
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>]
[& scope=<requested required rights>]
[& optional_scope=<requested optional rights>]
[& force_confirm=yes]
[& state=<arbitrary string>]
required parameters
Parameter |
Response |
|
Required response. When you request the confirmation code, specify the |
|
Application ID. Available in the app properties. To open properties, go to Yandex OAuth and click the app name. |
optional parameters
Parameter |
Description |
|
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 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. |
|
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 |
|
The URL to redirect the user to after they allow 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. |
|
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 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. |
|
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 |
|
Optional rights are requested in addition to the rights specified in the 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 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 |
|
Indicates that permission to access the account must be requested (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 |
|
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. |
Response format
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 parameter value in the request>]
Response parameters:
Property |
Description |
|
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. |
|
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 parameter value in 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 <encoded string `client_id:client_secret`>]
grant_type=authorization_code
& code=<verification code>
[& client_id=<app ID>]
[& client_secret=<secret key>]
[& device_id=<device ID>]
[& device_name=<device name>]
Required parameters
Parameter |
Description |
|
The method used to request the OAuth token. If you use a confirmation code, specify the |
|
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 |
|
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 |
|
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 |
|
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 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. |
|
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 |
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 |
|
Type of token issued. Always takes the |
|
An OAuth token with the requested rights or with the rights specified when registering the app. |
|
Token lifetime in seconds. |
|
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. |
|
The rights requested by the developer or specified when registering the app. The |
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 passedcode
parameter value isn't a 7-digit number. -
invalid_client
: The app with the specified ID (theclient_id
parameter) wasn't found or is blocked. This code is also returned if theclient_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
: Invalidgrant_type
parameter value. -
Basic auth required
: The authorization type specified in theAuthorization
header is notBasic
. -
Malformed Authorization header
: TheAuthorization
header isn't in<client_id>:<client_secret>
format, or this string isn't Base64-encoded.