Updating a token

Getting a token in exchange for a refresh token:

The app sends a POST request with the refresh token.
Yandex.OAuth returns a token and a new refresh token in the response body.

Note. The main token may not be updated if the remaining lifetime is long enough and there is no need to issue 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 be available only to your app, so we don't recommend saving it in browser cookies, open configuration files, and so on.

Exchange of refresh token for OAuth token

The app sends a refresh token, as well as its ID and password in the POST request.

POST /token HTTP/1.1
Host: 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=<app password>]


Parameter	Description
Required parameters
grant_type	The method used to request the OAuth token. If you use a refresh token, specify the “refresh_token” value.
refresh_token	Refresh-token received from Yandex.OAuth together with the OAuth token. The tokens have the same lifetime.
Advanced parameters
client_id	Application ID. Available in application properties (click the app name to open its properties). You can also pass the password and app ID in the authorization header.
client_secret	App password. Available in application properties (click the app name to open its properties). You can also pass the password and app ID in the authorization header.


Parameter	Description
Required parameters
grant_type	The method used to request the OAuth token. If you use a refresh token, specify the “refresh_token” value.
refresh_token	Refresh-token received from Yandex.OAuth together with the OAuth token. The tokens have the same lifetime.
Advanced parameters
client_id	Application ID. Available in application properties (click the app name to open its properties). You can also pass the password and app ID in the authorization header.
client_secret	App password. Available in application properties (click the app name to open its properties). You can also pass the password and app ID in the authorization header.

You can also send the app ID and password in the Authorization header by encoding the client_id>:<client_secret> string with the Base64 method. If Yandex.OAuth receives the Authorization header, the client_id and client_secret parameters in the request body are ignored.

Format of response with token

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
}


Key	Description
`access_token`	An OAuth token with the requested rights or with the rights specified when registering the 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.


Key	Description
`access_token`	An OAuth token with the requested rights or with the rights specified when registering the 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 description>",
  "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.
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.