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 a token and a new refresh token in the response body.

Alert

The main token may not change when you update it. That happens if it still has plenty of time before it expires, so there is no need to generate a new token. We recommend updating long-lived tokens every three months.

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.

Exchange of refresh token for OAuth token

Request format

The app sends a refresh token, as well as its ID and password in the 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. The tokens have the same lifetime.

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.

The secret key and app ID can also be passed 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.

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 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, while 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 permissions you requested or specified when registering your app.

refresh_token

A 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 a description of the error:

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

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 if the refresh token belongs to another application (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 a token
Next
Glossary