Web applications
Getting a token for a web application:
The application directs the user to the Yandex.OAuth page, where the user can grant access to personal data.
The user grants the application access.
Yandex.OAuth redirects the user to the address specified in the Callback URL field during registration. Token data is passed in the redirect URL after the # symbol.
The server environment might not transmit this part of the URL to the web application. In this case, data can be extracted from the address using JavaScript, or tokens can be obtained using an authorization code.
The application gets the redirect address and extracts the token.
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.
Token request URL
The application should direct the user to Yandex.OAuth at the following address:
https://oauth.yandex.com/authorize?
response_type=token
& client_id=<application ID>
[& device_id=<
device ID>
]
[& device_name=<
device name>]
[& display=popup]
[& 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 a token, specify the value “token”. |
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 If the |
display | Indicates the lightweight layout (without standard Yandex navigation) for the page for granting access. The lightweight layout should be requested if, for example, the page for granting access must be displayed in a small popup window. Only the “popup” value is processed. Other values are ignored. |
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 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 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 the scope parameter and the optional_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 If the 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 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 the scope parameter and the optional_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 a token, specify the value “token”. |
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 If the |
display | Indicates the lightweight layout (without standard Yandex navigation) for the page for granting access. The lightweight layout should be requested if, for example, the page for granting access must be displayed in a small popup window. Only the “popup” value is processed. Other values are ignored. |
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 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 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 the scope parameter and the optional_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 If the 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 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 the scope parameter and the optional_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. |
Response from Yandex.OAuth
Token data is passed in the redirect URL after the # symbol. If the server environment does not allow the application to receive this part of the URL, data can be extracted using JavaScript, or tokens can be obtained using an authorization code.
URL format with a token:
http://www.example.com/token#
access_token=<new OAuth token>
& expires_in=<token lifespan in seconds>
& token_type=bearer
[& state=<value of the state parameter in the request>]
Parameter | Description |
---|---|
access_token | The OAuth token with the requested permissions, or with the permissions specified when registering the application. |
expires_in | The token lifespan in seconds. |
token_type | Type of token issued. Always takes the value “bearer”. |
state | The value of the |
Parameter | Description |
---|---|
access_token | The OAuth token with the requested permissions, or with the permissions specified when registering the application. |
expires_in | The token lifespan in seconds. |
token_type | Type of token issued. Always takes the value “bearer”. |
state | The value of the |
If a token could not be issued, Yandex.OAuth appends the error code and description to the address. The description is in the language of the OAuth domain that the request was sent to. For example, for oauth.yandex.com
, text will be returned in English.
Format of the URL with error data:
http://www.example.com/token#
error=<error code>
& error_description=<error description>
[& state=<value of the state parameter in the request>]
Possible error codes:
access_denied
— The user denied the application access.unauthorized_client
— The application was rejected during moderation, or moderation is pending. This code is also returned if the application is blocked.
Extracting data from the URL using JavaScript
The part of the address after the # symbol is available in the JavaScript property document.location.hash
.
For example, the token can be obtained like this:
var token = /access_token=([^&]+)/.exec(document.location.hash)[1];