Getting a confirmation code from a URL

  1. 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.

  2. 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

response_type

Required 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.

optional 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

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.

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 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 scope and optional_scope parameters aren't passed, the token will be issued with the rights specified when registering the application.

optional_scope

Optional rights are requested in addition to the rights specified in the scope parameter.

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 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 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 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.

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

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 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

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.

You can also pass the password and app ID 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.

You can also pass the password and app ID in the Authorization header.

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.

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

token_type

Type of token issued. Always takes the bearer value.

access_token

An OAuth token with the requested rights or with the rights specified when registering the 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

The 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 description>",
   "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.

Previous
Requesting an OAuth token using the confirmation code
Next
Receiving a confirmation code from the user
In this article: