Refresh tokens

Refresh tokens are credentials that are used to obtain a new set of tokens without having to reauthenticate the user. Here, we discuss:

If you are looking for the /oauth/ endpoints, check out our OAuth section in the Identity API reference docs.

Refresh tokens overview

A refresh token is a credential that obtains an access token (and new refresh token). The refresh token itself does not communicate with the resource server, but instead is granted to the application along with the access token from the authentication server.

Check out the graphic below to get a better understanding of the typical refresh token flow.

You can also see the OAuth standards regarding refresh tokens here.

refresh token flow

  1. The client application requests an access token from the authentication server.

  2. The tokens (both access and refresh) are sent to the client application.

  3. The client application then sends the access token to the resource server.

  4. If successful, the resource server returns the protected resource.

    This continues as long as the access token is valid.

  5. If the access token has expired, an invalid token error is sent to the client application.

  6. If a refresh token was acquired at authorization grant, the client application sends the refresh token to the authentication server.

  7. The authentication server returns a new set of tokens (both access and refresh).

Because refresh tokens are long lived, it is possible to revoke the refresh token using the Identity API if needed.

Why use a refresh token?

Access tokens are typically short-lived (or they should be) and contain security measures like signatures in order to protect the resource server. You usually want to set the refresh token to have a much longer lifetime. This allows applications to retrieve new access tokens without prompting the user for reauthentication during the lifetime of the refresh token.

A refresh token can only be used once to retrieve a new access and refresh token, triggering the lifecycle of retrieving new tokens again.

Using refresh token rotation prevents old refresh tokens from obtaining new access tokens. This helps detect security threats by changing the refresh token with every refresh request.

If an application attempts to use a refresh token more than once, it invalidates all other tokens as well as the user session associated with the refresh token’s client_id.

When to use a refresh token

You should use a refresh token when the access token expires or is about to expire. You should not use a refresh token too often as this puts unnecessary strain our servers.

Enable refresh tokens via the console

To use refresh tokens, you can enable them via your ReachFive console. To do this, you must have the following:

Instructions

  1. Log in with your credentials to the ReachFive console.

  2. From the top ribbon, go to Settings.

  3. From the Sidebar, go to Clients.

  4. Within your First-party Identity Client, check Enable Refresh Tokens.

  5. Set the lifetime of the refresh token (default = 90). The lifetime range is between 1 and 365 days.

  6. Make sure you have offline_access set under Scopes.


If you have a public client, you must also…​

  1. Check Enforce PKCE security for authentication with the authorization code flow.

    enable refresh token console

    Enforcing PKCE forbids using the implicit flow.