Use a refresh token to use a token

Getting an access token in exchange for a refresh token:

  1. The application sends a POST request with a refresh token.

  2. Yandex.OAuth returns the access token and a new refresh 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.

Exchanging a refresh token for an OAuth token

The application sends the refresh token, 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=refresh_token
 & refresh_token=<refresh_token>
[& client_id=<application ID>]
[& client_secret=<application password>]
ParameterDescription
Required parameters

grant_type

Method of requesting an OAuth token.

If you are using a refresh token, set the value “refresh_token”.

refresh_token

The refresh token received from Yandex.OAuth with the OAuth token. Both tokens have the same lifespan.

Additional parameters

client_id

Application ID. Available in the application properties (click the name of the application to open its properties).

client_secret

Application password. Available in the application properties (click the name of the application to open its properties).

The application password and ID can also be passed in the Authorization header.

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

If a token could not be issued, the response contains an error description:

{
  "error_description": "<error description>",
  "error": "<error code>"
}

Possible error codes:

  • invalid_client ― The application with the specified ID (the client_id parameter) was not found or is blocked. This code is also returned if an invalid application password was passed in the client_secret parameter.
  • invalid_grant — Invalid or expired refresh token. This code is also returned if the refresh token belongs to another application (if it doesn't match the client_id that is passed).
  • invalid_request ― Invalid request format (one of the parameters in the body was omitted, or was specified twice).
  • unauthorized_client — The application was rejected during moderation, or moderation is pending.
  • unsupported_grant_type ― Unacceptable value for the grant_type parameter.
  • Basic auth required — The authorization type in the Authorization header is set to something other than Basic.
  • Malformed Authorization header — The Authorization header doesn't conform to the format <client_id>:<client_secret>, or this string isn't base64-encoded.