---
metadata:
  - name: generator
    content: Diplodoc Platform v5.44.0
alternate:
  - https://yandex.com/dev/id/doc/en/tokens/refresh-client.md
  - https://yandex.com/dev/id/doc/ru/tokens/refresh-client.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/id/doc/en/llms.txt

# Update a token

Getting a token in exchange for a refresh token:

1. The app sends a [POST request with the refresh token](#get-token).
    
1. Yandex OAuth returns a token and a new refresh token in the [response body](#refresh-response).
    
{% note 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.

{% endnote %}

<!-- source: en/_includes/oauth/security.md -->
The received token can be saved in the app and used for requests until its [lifetime expires](https://yandex.com/dev/id/doc/en/concepts/ya-oauth-intro.md#ttl). The token should only be available to your app, so we don't recommend saving it in the browser or open configuration files.
<!-- endsource: en/_includes/oauth/security.md -->

## Exchange of refresh token for OAuth token {#get-token}

### Request format {#refresh-request}

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](https://yandex.com/dev/id/doc/en/concepts/ya-oauth-intro.md#ttl). ||
|#

#### Advanced parameters
#|
|| **Parameter** | **Description** ||
|| `client_id` | Application ID. Available in the [app properties](https://yandex.com/dev/id/doc/en/register-client.md#app-params). To open properties, go to [Yandex OAuth](https://oauth.yandex.com/) and click the app name.

The secret key and app ID can also be passed in the [`Authorization` header](#auth-header). ||
|| `client_secret` | Secret key. Available in the [app properties](https://yandex.com/dev/id/doc/en/register-client.md#app-params). To open properties, go to [Yandex OAuth](https://oauth.yandex.com/) and click the app name.

The secret key and app ID can also be passed in the [`Authorization` header](#auth-header).
 ||
|#

<!-- source: en/_includes/oauth/reference/auto-code-client/id-auto-code-client/auth-header.md -->
Request parameters must be passed in the request body and must be URL-encoded.

{% note info %}

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. {#auth-header}

{% endnote %}
<!-- endsource: en/_includes/oauth/reference/auto-code-client/id-auto-code-client/auth-header.md -->

### Response format {#refresh-response}

{% list tabs %}

- Request successfully completed

   <!-- source: en/_includes/oauth/reference/auto-code-client/id-auto-code-client/reply-desc.md -->
   Yandex OAuth returns the OAuth token, refresh token, and their lifetime in JSON format:
   <!-- endsource: en/_includes/oauth/reference/auto-code-client/id-auto-code-client/reply-desc.md -->

   ```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
   }
   ```
   
   #|
   || **Parameter** | **Description** ||
   || `access_token` | An OAuth token with the permissions you requested or specified when [registering your app](https://yandex.com/dev/id/doc/en/register-client.md#access).
 ||
   || `refresh_token` | A token that can be used to [extend the lifetime](https://yandex.com/dev/id/doc/en/tokens/refresh-client.md) of the corresponding OAuth token. ||
   || `token_type` | Type of token issued. Always takes the `bearer` value.
 ||
   || `expires_in` | [Token lifetime](https://yandex.com/dev/id/doc/en/concepts/ya-oauth-intro.md#ttl) in seconds. 
 ||
   |#

- Request completed with an error

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

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

   Error codes:
   
   * <!-- source: en/_includes/oauth/errors/invalid-client.md -->
     `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.
     <!-- endsource: en/_includes/oauth/errors/invalid-client.md -->

   * `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).
   
   * <!-- source: en/_includes/oauth/errors/invalid-request.md -->
     `invalid_request`: Invalid request format (one of the parameters isn't specified, specified twice, or isn't passed in the request body).
     <!-- endsource: en/_includes/oauth/errors/invalid-request.md -->
   
   * <!-- source: en/_includes/oauth/errors/unauthorized-client.md -->
     `unauthorized_client`: The app was rejected during moderation or is awaiting moderation. Also returned if the app is blocked.
     <!-- endsource: en/_includes/oauth/errors/unauthorized-client.md -->
   
   * <!-- source: en/_includes/oauth/errors/grant-type.md -->
     `unsupported_grant_type`: Invalid `grant_type` parameter value.
     <!-- endsource: en/_includes/oauth/errors/grant-type.md -->
   
   * <!-- source: en/_includes/oauth/errors/basic-auth.md -->
     `Basic auth required`: The authorization type specified in the `Authorization` header is not <q>Basic</q>.
     <!-- endsource: en/_includes/oauth/errors/basic-auth.md -->
   
   * <!-- source: en/_includes/oauth/errors/mailformed.md -->
     `Malformed Authorization header`: The `Authorization` header isn't in `<client_id>:<client_secret>` format, or this string isn't Base64-encoded.
     <!-- endsource: en/_includes/oauth/errors/mailformed.md -->

{% endlist %}