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
Content-type: application/x-www-form-urlencoded
Content-Length: <length of the request body>
[Authorization: Basic <encoded client_id:client_secret string>]

 & refresh_token=<refresh_token>
[& client_id=<application ID>]
[& client_secret=<application password>]
Parameter Description
Required parameters


Method of requesting an OAuth token.

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


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

Additional parameters


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


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

The OAuth token with the requested permissions, or with the permissions specified when registering the application.


Refresh token.


Type of token issued. Always takes the value “bearer”.


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.