Web app
Getting a token for a web app:
The app directs the user to the Yandex.OAuth page, where they can allow access to their data.
The user allows access to the app.
Yandex.OAuth redirects the user to the URL specified in the Callback URL field during registration. The token data is passed to the redirect URL after the # character.
The server environment may not pass this part of the URL to the web app. In this case, you can retrieve data from the URL with JavaScript, or receive tokens with the confirmation code.
The app gets the redirect URL and retrieves the token.
The received token can be saved in the app and used for requests until its lifetime expires. The token should be available only to your app, so we don't recommend saving it in browser cookies, open configuration files, and so on.
URL for requesting the token
The app should direct the user to Yandex.OAuth at the following URL:
https://oauth.yandex.com/authorize?
response_type=token
& client_id=<app ID>
[& device_id=<device ID>]
[& device_name=<device name>]
[& redirect_uri=<redirect address>]
[& login_hint=<user name or email address>]
[& scope=<requested required rights>]
[& optional_scope=<requested optional rights>]
[& force_confirm=yes]
[& state=<arbitrary string>]
[& display=popup]| Parameter | Description |
|---|---|
| Required parameters | |
| response_type | Expected response. The token request should contain the “token” value. |
| client_id | Application ID. Available in application properties (click the app name to open its properties). |
| Advanced parameters | |
| 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). Restriction. An app can have up to 20 tokens linked to a user's devices. If Yandex.OAuth issues a new device token for the app, the oldest token stops working. Learn more about tokens for individual devices at Token for a device. |
| 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 If the |
| redirect_uri | The URL to redirect the user to after they allow or deny access to the app. By default, the first Callback URI specified in the 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, as well as 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. |
| scope | A list of access rights currently required by the application, separated by a space. Rights must be requested from the list defined when registering the application. You can find out the allowed rights at the link https://oauth.yandex.com/client/<client_id>/info, specifying the application ID instead of <client_id>. If the This parameter allows you to get a token only with the rights currently required by the app. Note. All access rights are requested at once via the scope and optional_scope parameters, are considered optional, and are not required for the app to function. The user decides which requested optional rights to grant. |
| optional_scope | A list of optional access rights, separated by a space, that aren't required for the app functionality. Optional rights are requested in addition to the rights specified in the If the 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 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 application and choose the Yandex account. 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. |
| display | Indicates a lightweight layout (without standard Yandex navigation) for the access permission page. You should request a lightweight layout, for example, if you want to display a permission page in a small pop-up window. Only the “popup” value is processed. Other values are ignored. |
| Parameter | Description |
|---|---|
| Required parameters | |
| response_type | Expected response. The token request should contain the “token” value. |
| client_id | Application ID. Available in application properties (click the app name to open its properties). |
| Advanced parameters | |
| 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). Restriction. An app can have up to 20 tokens linked to a user's devices. If Yandex.OAuth issues a new device token for the app, the oldest token stops working. Learn more about tokens for individual devices at Token for a device. |
| 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 If the |
| redirect_uri | The URL to redirect the user to after they allow or deny access to the app. By default, the first Callback URI specified in the 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, as well as 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. |
| scope | A list of access rights currently required by the application, separated by a space. Rights must be requested from the list defined when registering the application. You can find out the allowed rights at the link https://oauth.yandex.com/client/<client_id>/info, specifying the application ID instead of <client_id>. If the This parameter allows you to get a token only with the rights currently required by the app. Note. All access rights are requested at once via the scope and optional_scope parameters, are considered optional, and are not required for the app to function. The user decides which requested optional rights to grant. |
| optional_scope | A list of optional access rights, separated by a space, that aren't required for the app functionality. Optional rights are requested in addition to the rights specified in the If the 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 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 application and choose the Yandex account. 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. |
| display | Indicates a lightweight layout (without standard Yandex navigation) for the access permission page. You should request a lightweight layout, for example, if you want to display a permission page in a small pop-up window. Only the “popup” value is processed. Other values are ignored. |
The Yandex.OAuth response
The token data is passed to the redirect URL after the # character.If the server environment doesn't allow the app to get this part of the URL, you can extract the data with JavaScript or get tokens with the confirmation code.
Token URL format:
http://www.example.com/token#
access_token=<new OAuth token>
& expires_in=<token lifetime in seconds>
& token_type=bearer
[& state=<the value of the state parameter in the request>]
[& scope=<access rights>]
| Parameter | Description |
|---|---|
access_token | An OAuth token with the requested rights or with the rights specified when registering the app. |
expires_in | Token lifetime in seconds. |
token_type | Type of token issued. Always takes the “bearer” value. |
state | The |
scope | Rights requested by the developer or specified when registering the app. The |
| Parameter | Description |
|---|---|
access_token | An OAuth token with the requested rights or with the rights specified when registering the app. |
expires_in | Token lifetime in seconds. |
token_type | Type of token issued. Always takes the “bearer” value. |
state | The |
scope | Rights requested by the developer or specified when registering the app. The |
If the token could not be issued, then Yandex.OAuth adds the error code and description to the URL. The description is in the language of the OAuth domain the request was sent to: for example, for oauth.yandex.com, the text will be returned in English.
Format of the URL with error information:
http://www.example.com/token#
error=<error code>
& error_description=<error description>
[& state=<the value of the state parameter in the request>]Error codes:
access_denied: The user denied access to the app.unauthorized_client: The app was rejected during moderation or is awaiting moderation. Also returned if the app is blocked.
Extracting URL data with JavaScript
The URL part after the # character is available in the document.location.hash JavaScript property.
For example, you can get the token like this:
var token = /access_token=([^&]+)/.exec(document.location.hash)[1];