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 (theclient_id
parameter) was not found or is blocked. This code is also returned if an invalid application password was passed in theclient_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 thegrant_type
parameter.Basic auth required
— The authorization type in theAuthorization
header is set to something other thanBasic
.Malformed Authorization header
— TheAuthorization
header doesn't conform to the format<client_id>:<client_secret>
, or this string isn't base64-encoded.