[Yandex Cloud documentation](../../../index.md) > [Yandex Identity and Access Management](../../index.md) > [Concepts](../index.md) > [Authentication](index.md) > Refresh token

# Refresh token

A _refresh token_ is a type of credential that allows an OAuth application to automatically obtain a new IAM token after the user's [IAM token](iam-token.md) expires. A refresh token is issued for a user and sent to an OAuth application, which then authenticates the user in Yandex Cloud.

An example of an OAuth application supporting refresh tokens is the [Yandex Cloud CLI](../../../cli/index.md). Refresh tokens can be issued to users with any [account](../users/accounts.md) type.

With the Yandex Cloud CLI and [API](../../api-ref/RefreshToken/index.md), you can [view](../../operations/refresh-token/list.md) the list of refresh tokens issued for a user and [revoke](../../operations/refresh-token/revoke.md) such tokens. If you have a Yandex account, you can view the list of your refresh tokens on the [My account](https://myaccount.yandex.cloud/) portal.

## Refresh token lifetime {#token-lifetime}

A refresh token is valid for 31 days. If used to obtain an IAM token, a refresh token is automatically reissued when there are less than seven days left before its expiration.

If your refresh token has expired, you must obtain a new one. A new refresh token will be created automatically when next obtain an IAM token. In this case, the user will have to re-authenticate in the browser. 

Refresh tokens are automatically deleted seven days after their expiration.

## Enabling the use of refresh tokens in the Yandex Cloud CLI {#token-enabling}

To use refresh tokens in the Yandex Cloud CLI, you must enable this option at the Yandex Identity Hub level. Proceed as follows:

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

  1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization) using an administrator or organization owner account.

      [Switch](../../../organization/operations/manage-organizations.md#switch-to-another-org) to an organization of your choice as required.
  1. In the left-hand panel, select ![shield](../../../_assets/console-icons/shield.svg) **Security settings**.
  1. Under **Authentication settings**, check **Enable refresh tokens**.
  1. Optionally, to use enhanced refresh token [security](refresh-token.md#dpop-verification) using DPoP keys with their obligatory storage on a [YubiKey](https://developers.yubico.com/Passkeys/), enable **Allow DPoP key storage only on YubiKeys**.

      With this option disabled, you can use DPoP keys saved both on a YubiKey and the user's local file system to ensure refresh token security.

{% endlist %}

To use refresh tokens in the Yandex Cloud CLI, each user must [initialize DPoP](refresh-token.md#enabling-dpop) after you enable this option at the organization level.

## Using DPoP to protect refresh tokens in the Yandex Cloud CLI {#dpop-verification}

The [DPoP](https://datatracker.ietf.org/doc/html/rfc9449) mechanism helps to prove that a request for an IAM token made with a refresh token is legitimate. This verification is based on a special DPoP key created on the user device to confirm the authenticity of both the user making the request and the source device.

If the **Allow DPoP key storage only on YubiKeys** option is [disabled](#token-enabling), to protect your refresh tokens, you can use DPoP keys saved both on a YubiKey and user's local file system (a less secure option).

To enhance the protection of refresh tokens, enable **Allow DPoP key storage only on YubiKeys** to only use DPoP keys stored on a specialized YubiKey device, which ensures the keys are not retrievable.

### Initializing DPoP protection for refresh tokens in the Yandex Cloud CLI {#enabling-dpop}

The DPoP key used to verify the user and device sending a request for an IAM token must be created on the user device. The mechanism for creating, storing, and using such a DPoP key must be implemented within an OAuth application that uses refresh tokens.

To initialize DPoP protection for a federated user's refresh tokens in the Yandex Cloud CLI:

1. Make sure the use of refresh tokens is [enabled](#token-enabling) in Yandex Identity Hub at your organization level.
1. Initialize DPoP protection for refresh tokens on the user device:

    {% list tabs group=instructions %}

    - Yandex Cloud CLI {#cli}

      1. [Create](../../../cli/operations/authentication/federated-user.md) a CLI profile for the federated user and authenticate as this user in Yandex Cloud.
      1. Initialize the DPoP protection:

          ```bash
          yc init --dpop
          ```

          The Yandex Cloud CLI will prompt you to configure the DPoP protection:
          
          ```text
          Welcome! This command will take you through the configuration process.
          Do you want to initialize file system auth keys? [y/N]
          ```
      1. Complete the configuration process. To do this, type `y` and press `ENTER`.

          Follow the configurator tips to generate and save a DPoP key in your local file system or a YubiKey.

    {% endlist %}

Once initialization is complete, a refresh token will be created for the user the next time they request a new IAM token. Later on, the Yandex Cloud CLI will automatically update IAM tokens for the federated user, requiring no regular authentication in the browser.

If the DPoP key is stored in the file system, the IAM token is reissued immediately. When using a YubiKey, the IAM token can only be reissued after confirming the action on the YubiKey.