Update a token

Getting a token in exchange for a refresh token:

  1. The app sends a POST request with the refresh token.

  2. Yandex OAuth returns an access token and a new refresh token in the response body.

Note

The main token may not get updated if the remaining lifetime is long enough and there is no need to issue a new token. We recommend updating long-living tokens every three months.

The obtained token can be saved in the app and used for API requests until its lifetime ends. Only your app should have access to the token, so avoid saving it in the browser or public configuration files.

Exchange the refresh token for an OAuth token

Request format

The app sends its ID and secret key along with the refresh token in a POST request.

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=refresh_token
 & refresh_token=<refresh_token>
[& client_id=<app ID>]
[& client_secret=<secret key>]

Required parameters

Parameter

Description

grant_type

The method used to request the OAuth token.

If you use a refresh token, specify the refresh_token value.

refresh_token

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

Optional parameters

Parameter

Description

client_id

The app ID. It can be found in the app properties. To open them, go to Yandex OAuth and select the app name.

The secret key and app ID can also be passed in the Authorization header.

client_secret

The secret key. It can be found in the app properties. To open them, go to Yandex OAuth and select the app name.

The secret key and app ID can also be passed in the Authorization header.

Request parameters must be passed in the request body and must be URL-encoded.

Note

To pass the app ID and secret key in the Authorization header, encode the string <client_id>:<client_secret> with Base64.

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

{
"access_token": "AQAAAACy1C6ZAAAAfa6vDLuItEy8pg-iIpnDxIs",
"refresh_token": "1:GN686QVt0mmakDd9:A4pYuW9LGk0_UnlrMIWklkAuJkUWbq27loFekJVmSYrdfzdePBy7:A-2dHOmBxiXgajnD-kYOwQ",
"token_type": "bearer",
"expires_in": 124234123534
}

Parameter

Description

access_token

An OAuth token with the requested rights or with the rights specified when registering the app.

refresh_token

The token that can be used to extend the lifetime of the corresponding OAuth token.

token_type

Type of token issued. Always takes the bearer value.

expires_in

Token lifetime in seconds.

If a token couldn't be issued, the response contains an error description:

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

Possible error codes:

  • 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 refresh token. This code is also returned when the refresh token belongs to another app (doesn't match the passed client_id).

  • invalid_request: Invalid request format (one of the parameters isn't specified, specified twice, or isn't passed in the request body).

  • 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
Revoke tokens
Next
Feedback