Token for a code entered by the user
Some applications (for example, applications for consoles or that are installed on Smart TVs) are not able to get the authorization code from the URL. In this case, users must get the code from Yandex.OAuth and enter it in the application themselves.
Obtaining a token in exchange for a code entered by the user:
The application opens the Yandex.OAuth page in the browser, where the user can grant access to personal data.
If the device where the application is installed doesn't have a browser, the user will have to go to the appropriate address on a computer. To make it easier to enter the address, provide a QR code or short link for the user.
The user goes to the open page or short link and allows access for the application.
Yandex.OAuth displays the authorization code. (For this to happen, the Callback URL application parameter must indicate the address
https://oauth.yandex.ru/verification_code
).The application sends a POST request with the code.
Yandex.OAuth returns a token in the message body.
The received token can be saved in the application and used for API requests until its lifespan expires. The token must only be accessible to your application, so we do not recommend storing it in browser cookies, open configuration files, and so on.
Getting an authorization code
The application should direct the user to Yandex.OAuth at the following address:
https://oauth.yandex.com/authorize? response_type=code & client_id=<application ID> [& device_id=<device ID>] [& device_name=<device name>] [& login_hint=<username or email>] [& scope=<necessary permissions requested>] [& optional_scope=<optional permissions requested>] [& force_confirm=yes] [& state=<any string>]
Parameter Description Required parameters response_type
Required response.
When requesting an authorization code, specify the value “code”.
client_id
Application ID. Available in the application properties (click the name of the application to open its properties).
Additional parameters device_id Unique ID of the device that the token is being requested for. To ensure uniqueness, it is sufficient to generate the UUID once and use it for every request for a new token from this device.
The ID must be at least 6 characters and no more than 50. Only printable ASCII symbols are allowed (codes 32 through 126).
Restriction. An application can't have more than 20 tokens associated with devices for a specific user. If Yandex.OAuth successfully issues the application a new token for a device, the oldest token stops working.For more information about device tokens, see Device token.
device_name The device name to show to users. Maximum of 100 characters.
For mobile devices, we recommend passing the device name set by the user. If it does not have a name, you can make one up using the device model, OS name and version, and so on.
If the
device_name
parameter was passed without thedevice_id
parameter, it will be ignored. Yandex.OAuth can only issue a regular token that is not associated with the device.If the
device_id
parameter was passed without thedevice_name
parameter, the user interface will show the token as issued for an unknown device.login_hint Explicitly identifies the account that the token is being requested for. The parameter value can pass a Yandex account username, or an email address for Yandex.Mail or Yandex.Mail for Domain.
This parameter helps the user log in on Yandex with the account that the application needs to access. After getting the parameter, Yandex.OAuth checks the user's authorization:
If the user is already logged in under the necessary account, Yandex.OAuth just asks for permission to access data.
If the user isn't logged in under the necessary account, the service displays the Yandex login page with this parameter value shown in the username field. Keep in mind that the token won't necessarily be requested for the account shown: the user might delete the pre-filled username and log in with another one.
If the parameter specifies a non-existent account, Yandex.OAuth can only inform the user of this. The application will have to request the token over again.
scope A space-separated list of permissions that the application needs at this time. The requested permissions must be from the list that was specified when registering the application. To find out which permissions are available, go to https://oauth.yandex.com/client/<client_id>/info (specify the application's ID in place of <client_id>).
If the
scope
andoptional_scope
parameters were omitted from the request, the token is issued with the permissions that were specified when registering the application.This parameter lets you get a token for just the permissions that the application needs right now.
Note. Access permissions that are requested using both thescope
parameter and theoptional_scope
parameter simultaneously are treated as optional permissions that the application can do without. The user can decide which of the requested permissions to grant the application, and which ones to refuse.optional_scope A list of space-separated optional access permissions that the application can function without. Optional permissions are requested in addition to the permissions specified in the
scope
parameter. Optional permissions must be from the list that was specified when registering the application. To find out which permissions are available, go to https://oauth.yandex.com/client/<client_id>/info (specify the application's ID in place of <client_id>).If the
scope
andoptional_scope
parameters were omitted from the request, the token is issued with the permissions that were specified when registering the application.The user can decide which of the requested permissions to grant the application, and which ones to refuse. The token is issued with the permissions specified in the
scope
parameter and the permissions from theoptional_scope
parameter that the user selected.For example, you can use this parameter if the application requires the user's email address for registration, while access to the user's profile picture is preferable, but not required.
Note. Access permissions that are requested using both thescope
parameter and theoptional_scope
parameter simultaneously are treated as optional permissions.force_confirm Indicates that the application must ask the user for permission to access the account (even if the user has already granted access for this application). When it gets this parameter, Yandex.OAuth asks the user to allow the application access and to select the desired Yandex account.
This parameter is processed if the value is set to “yes”, “true”, or “1”. If any other value is set, the parameter is ignored.
state The state string, which Yandex.OAuth returns without making any changes. The maximum length of the string is 1024 characters.
For example, you can use it for protection from CSRF attacks or for identifying the user that a token is requested for.
Parameter Description Required parameters response_type
Required response.
When requesting an authorization code, specify the value “code”.
client_id
Application ID. Available in the application properties (click the name of the application to open its properties).
Additional parameters device_id Unique ID of the device that the token is being requested for. To ensure uniqueness, it is sufficient to generate the UUID once and use it for every request for a new token from this device.
The ID must be at least 6 characters and no more than 50. Only printable ASCII symbols are allowed (codes 32 through 126).
Restriction. An application can't have more than 20 tokens associated with devices for a specific user. If Yandex.OAuth successfully issues the application a new token for a device, the oldest token stops working.For more information about device tokens, see Device token.
device_name The device name to show to users. Maximum of 100 characters.
For mobile devices, we recommend passing the device name set by the user. If it does not have a name, you can make one up using the device model, OS name and version, and so on.
If the
device_name
parameter was passed without thedevice_id
parameter, it will be ignored. Yandex.OAuth can only issue a regular token that is not associated with the device.If the
device_id
parameter was passed without thedevice_name
parameter, the user interface will show the token as issued for an unknown device.login_hint Explicitly identifies the account that the token is being requested for. The parameter value can pass a Yandex account username, or an email address for Yandex.Mail or Yandex.Mail for Domain.
This parameter helps the user log in on Yandex with the account that the application needs to access. After getting the parameter, Yandex.OAuth checks the user's authorization:
If the user is already logged in under the necessary account, Yandex.OAuth just asks for permission to access data.
If the user isn't logged in under the necessary account, the service displays the Yandex login page with this parameter value shown in the username field. Keep in mind that the token won't necessarily be requested for the account shown: the user might delete the pre-filled username and log in with another one.
If the parameter specifies a non-existent account, Yandex.OAuth can only inform the user of this. The application will have to request the token over again.
scope A space-separated list of permissions that the application needs at this time. The requested permissions must be from the list that was specified when registering the application. To find out which permissions are available, go to https://oauth.yandex.com/client/<client_id>/info (specify the application's ID in place of <client_id>).
If the
scope
andoptional_scope
parameters were omitted from the request, the token is issued with the permissions that were specified when registering the application.This parameter lets you get a token for just the permissions that the application needs right now.
Note. Access permissions that are requested using both thescope
parameter and theoptional_scope
parameter simultaneously are treated as optional permissions that the application can do without. The user can decide which of the requested permissions to grant the application, and which ones to refuse.optional_scope A list of space-separated optional access permissions that the application can function without. Optional permissions are requested in addition to the permissions specified in the
scope
parameter. Optional permissions must be from the list that was specified when registering the application. To find out which permissions are available, go to https://oauth.yandex.com/client/<client_id>/info (specify the application's ID in place of <client_id>).If the
scope
andoptional_scope
parameters were omitted from the request, the token is issued with the permissions that were specified when registering the application.The user can decide which of the requested permissions to grant the application, and which ones to refuse. The token is issued with the permissions specified in the
scope
parameter and the permissions from theoptional_scope
parameter that the user selected.For example, you can use this parameter if the application requires the user's email address for registration, while access to the user's profile picture is preferable, but not required.
Note. Access permissions that are requested using both thescope
parameter and theoptional_scope
parameter simultaneously are treated as optional permissions.force_confirm Indicates that the application must ask the user for permission to access the account (even if the user has already granted access for this application). When it gets this parameter, Yandex.OAuth asks the user to allow the application access and to select the desired Yandex account.
This parameter is processed if the value is set to “yes”, “true”, or “1”. If any other value is set, the parameter is ignored.
state The state string, which Yandex.OAuth returns without making any changes. The maximum length of the string is 1024 characters.
For example, you can use it for protection from CSRF attacks or for identifying the user that a token is requested for.
When the user grants access to personal data, Yandex.OAuth outputs an authorization code. The lifespan of this code is 10 minutes. When it expires, a code must be requested again.
Exchanging an authorization code for a token
The application sends the code, along with its ID and password, in a POST request.
POST /token HTTP/1.1
Host: oauth.yandex.com
Content-type: application/x-www-form-urlencoded
Content-Length: <length of the request body>
[Authorization: Basic <encoded client_id:client_secret
string>]
grant_type=authorization_code
& code=<confirmation code>
[& client_id=<application ID>]
[& client_secret=<application password>]
[& device_id=<device ID>]
[& device_name=<device name>]
Parameter | Description |
---|---|
Required parameters | |
grant_type | Method of requesting an OAuth token. If you are using the authorization code, enter the value of “authorization_code”. |
code | The authorization code received from Yandex.OAuth. The lifespan of this code is 10 minutes. When it expires, a code must be requested again. |
Parameter | Description |
Additional parameters | |
client_id | Application ID. Available in the application properties (click the name of the application to open its properties). The application ID and password must be passed either in the request parameters or in the Authorization header. |
client_secret | Application password. Available in the application properties (click the name of the application to open its properties). The application ID and password must be passed either in the request parameters or in the Authorization header. |
device_id | The ID of the device that the token is being requested for. If the ID was set in the device_id parameter when requesting the authorization code, the |
device_name | The name of the device that the token is being requested for. If the |
Parameter | Description |
---|---|
Required parameters | |
grant_type | Method of requesting an OAuth token. If you are using the authorization code, enter the value of “authorization_code”. |
code | The authorization code received from Yandex.OAuth. The lifespan of this code is 10 minutes. When it expires, a code must be requested again. |
Parameter | Description |
Additional parameters | |
client_id | Application ID. Available in the application properties (click the name of the application to open its properties). The application ID and password must be passed either in the request parameters or in the Authorization header. |
client_secret | Application password. Available in the application properties (click the name of the application to open its properties). The application ID and password must be passed either in the request parameters or in the Authorization header. |
device_id | The ID of the device that the token is being requested for. If the ID was set in the device_id parameter when requesting the authorization code, the |
device_name | The name of the device that the token is being requested for. If the |
The application ID and password can also be sent in the Authorization
header by encoding the client_id>:<client_secret>
string using base64. If Yandex.OAuth receives the Authorization
header, the client_id
and client_secret
parameters in the request body are ignored.
Response format with a token
Yandex.OAuth returns the OAuth token, the refresh token, and their lifespans in JSON:
200 OK
Content-type: application/json
{
"access_token": "AQAAAACy1C6ZAAAAfa6vDLuItEy8pg-iIpnDxIs",
"refresh_token": "1:GN686QVt0mmakDd9:A4pYuW9LGk0_UnlrMIWklkAuJkUWbq27loFekJVmSYrdfzdePBy7:A-2dHOmBxiXgajnD-kYOwQ",
"token_type": "bearer",
"expires_in": 124234123534
}
Key | Description |
---|---|
access_token | The OAuth token with the requested permissions, or with the permissions specified when registering the application. |
refresh_token | Refresh token. |
token_type | Type of token issued. Always takes the value “bearer”. |
expires_in | The token lifespan in seconds. |
Key | Description |
---|---|
access_token | The OAuth token with the requested permissions, or with the permissions specified when registering the application. |
refresh_token | Refresh token. |
token_type | Type of token issued. Always takes the value “bearer”. |
expires_in | The token lifespan in seconds. |
The lifespan of a refresh token is the same as the OAuth token's lifespan.
If a token could not be issued, the response contains an error description:
{
"error_description": "<error description>",
"error": "<error code>"
}
Possible error codes:
bad_verification_code
— The passed value of thecode
parameter is not a 7-digit number.invalid_client
― The application with the specified ID (theclient_id
parameter) was not found or is blocked. This code is also returned if an invalid application password was passed in theclient_secret
parameter.invalid_grant
― Invalid or expired authorization code.invalid_request
― Invalid request format (one of the parameters in the body was omitted, or was specified twice).invalid_scope
— The application's permissions changed after the authorization code was generated.unauthorized_client
— The application was rejected during moderation, or moderation is pending.unsupported_grant_type
― Unacceptable value for thegrant_type
parameter.Basic auth required
— The authorization type in theAuthorization
header is set to something other thanBasic
.Malformed Authorization header
— TheAuthorization
header doesn't conform to the format<client_id>:<client_secret>
, or this string isn't base64-encoded.