---
title: Refresh tokens
description: Refresh tokens (RFC 6749) are a type of token that can be used to obtain a new access token that may have identical or narrower scopes than the original. AM can issue refresh tokens during every OAuth 2.0/OpenID Connect grant flow, except for the implicit and the client credentials grant flows.
component: pingam
version: 7.2
page_id: pingam:oauth2-guide:oauth2-refresh-tokens
canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-refresh-tokens.html
llms_txt: https://docs.pingidentity.com/pingam/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
superseded_by: https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-refresh-tokens.html
section_ids:
  enable-refresh-tokens: Configure AM to issue refresh tokens
  refresh-access-token: Refresh an access token
---

# Refresh tokens

Refresh tokens ([RFC 6749](https://www.rfc-editor.org/info/rfc6749)) are a type of token that can be used to obtain a new access token that may have identical or narrower scopes than the original. AM can issue refresh tokens during every OAuth 2.0/OpenID Connect grant flow, except for the implicit and the client credentials grant flows.

> **Collapse: Why are refresh tokens useful?**
>
> Access tokens are short-lived because, if leaked, they grant potentially malicious users access to a resource owner's resources. However, a client may need to access a protected resource for a period of time that exceeds the access token lifetime, or when the resource owner is not available. In some cases, it is unreasonable to ask for the resource owner's consent several times during the same operation.
>
> Refresh tokens solve this problem by letting clients request a new access token, without further interaction from the resource owner. Although a malicious user with a compromised access token has access to the resource, a user who holds a refresh token must *also* have a compromised client ID and client secret to obtain an access token. This is because the client must *authenticate* to the token endpoint to obtain an access token using a refresh token.

Refresh tokens are long-lived by default. You can configure the lifetime of refresh tokens in the OAuth 2.0 provider settings, or in each client. By default, the configuration of the OAuth 2.0 provider is used. For more information, see the [OAuth2 provider attributes](../reference/global-services-configuration.html#global-oauth-oidc) and the OAuth 2.0 client [Advanced properties](oauth2-register-client.html#configure-oauth2-oidc-client-advanced)

You can configure a *grace period*, [on the OAuth2.0 provider](../reference/global-services-configuration.html#refresh-token-grace-period-provider) or [per OAuth 2.0 client](oauth2-register-client.html#refresh-token-grace-period-client), during which refresh tokens can be reused. Refresh tokens can also be revoked (see [/oauth2/token/revoke](varlist-oauth2-token-revoke-endpoint.html)).

## Configure AM to issue refresh tokens

AM can issue refresh tokens during the following actions:

* When issuing an access token to the client after a successful OAuth 2.0 grant flow.

* When the client successfully uses a refresh token to obtain a new access token.

|   |                                                                           |
| - | ------------------------------------------------------------------------- |
|   | When a new refresh token is issued, the old refresh token is deactivated. |

1. To let AM issue refresh tokens at the same time the access token is issued, go to Realms > *Realm Name* > Services > OAuth2 Provider > Core, and enable Issue Refresh Tokens.

   Note that you configure refresh tokens at the realm level. Consider carefully the types of clients registered to the realm before configuring AM to issue refresh tokens.

2. To let AM issue refresh tokens when refreshing access tokens, go to Realms > *Realm Name* > Services > OAuth2 Provider > Core, and enable Issue Refresh Tokens on Refreshing Access Tokens.

3. Save your changes.

4. To configure a client to use the `Refresh Token` grant flow perform the following steps:

   * Go to Realms > *Realm Name* > Applications > OAuth 2.0 > *Client Name* > Advanced.

   * In the Grant Types field, add the `Refresh Token` grant type.

   * Save your changes.

## Refresh an access token

This procedure assumes the following configuration:

* AM is configured as an OAuth 2.0 authorization server with the following configuration:

  * **Issue Refresh Tokens** is enabled.

  * **Issue Refresh Tokens on Refreshing Access Tokens** is enabled.

  * The `Refresh Token` grant type is configured in the Grant Types field.

  For more information, see [Authorization server configuration](oauth2-configure-authz.html).

* A confidential client called `myClient` is registered in AM with the following configuration:

  * **Client secret**: `forgerock`

  * **Scopes**: `write read`

  * **Grant Types**: `Authorization Code Refresh Token`

Perform the steps in the procedure to refresh an access token:

1. The client obtains an access token and a refresh token using the Authorization Code Grant flow.

   For more information, see [Authorization code grant](oauth2-authz-grant.html).

   The example assumes the refresh token is `qz1qx-9AYOkRp3AWcCZULvPitpM`.

2. The client makes a POST call to the authorization's server token endpoint, specifying, at least, the following parameters:

   * **grant_type**=refresh_token

   * **refresh_token**=*your-refresh-token*

   For more information about the parameters supported by the `/oauth2/access_token` endpoint, see [/oauth2/access_token](oauth2-access_token-endpoint.html).

Confidential clients can authenticate to the OAuth 2.0 endpoints in several ways. This example uses the following form parameters:

* **client_id**=*your-client-id*

* **client_secret**=*your-client-secret*

For more information, see [OAuth 2.0 client authentication](oauth2-client-auth.html).

If the OAuth 2.0 provider is configured for a subrealm rather than the Top Level Realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the `/alpha` realm, use `/oauth2/realms/root/realms/alpha/access_token`.

For example:

```bash
$ curl \
--request POST \
--data "grant_type=refresh_token" \
--data "refresh_token=qz1qx-9AYOkRp3AWcCZULvPitpM" \
--data "client_id=myClient" \
--data "client_secret=forgerock" \
--data "scope=read" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"
{
   "access_token":"y-C_A1RKJIg-BUlKhp—​kv5Iywk",
   "refresh_token":"qdqVnFJK8FjiQAjYMaBuUY6z_HU",
   "scope":"read",
   "token_type":"Bearer",
   "expires_in":3599
}
```

|   |                                                                                                                                                                                                                                                                                           |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | The `scope` parameter is not required. By default, AM will issue an access token with the same scopes of the original. This example is restricting the new access token to the `read` scope.Also note that AM has issued a new refresh token; the original refresh token is now inactive. |