Use a refresh token to use a token

Getting an access token in exchange for a refresh token:

The application sends a POST request with a refresh token.
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>]


Parameter	Description
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). The application password and ID can also be passed in the Authorization header.
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.


Parameter	Description
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). The application password and ID can also be passed in the Authorization header.
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
}


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


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