Refresh Token


The Refresh Token grant type is used to obtain additional access tokens in order to prolong the client’s authorization of a user’s resources.

Read more about refresh tokens

Use Cases


Create an instance of OAuth2\GrantType\RefreshToken and add it to your server

// create a storage object to hold refresh tokens
$storage = new OAuth2\Storage\Pdo(array('dsn' => 'sqlite:refreshtokens.sqlite'));

// create the grant type
$grantType = new OAuth2\GrantType\RefreshToken($storage);

// add the grant type to your OAuth server

Note: Refresh tokens are only provided when retrieving a token using the Authorization Code or User Credentials grant types.

Note: Refresh tokens will only be returned if a storage implementing OAuth2\Storage\RefreshTokenInterface is provided to your instance of OAuth2\Server.


The Refresh Token grant type has the following configuration:

For example:

// the refresh token grant request will have a "refresh_token" field
// with a new refresh token on each request
$grantType = new OAuth2\GrantType\RefreshToken($storage, array(
    'always_issue_new_refresh_token' => true

The Access Token return type has the following configuration:

For example:

// the refresh tokens now last 28 days
$accessToken = new OAuth2\ResponseType\AccessToken($accessStorage, $refreshStorage, array(
    'refresh_token_lifetime' => 2419200,

$server = new OAuth2\Server($storage, $config, $grantType, array($accessToken));

However, both of these configuration options can be sent in when the server is created using the server’s configuration array:

$server = new OAuth2\Server($storage, array(
    'always_issue_new_refresh_token' => true,
    'refresh_token_lifetime'         => 2419200,

Example Request

First, a refresh token must be retrieved using the Authorizaton Code or User Credentials grant types:

$ curl -u TestClient:TestSecret -d 'grant_type=password&username=bshaffer&password=brent123'

The access token will then contain a refresh token:

    "token_type": "bearer",

This refresh token can then be used to generate a new access token of equal or lesser scope:

$ curl -u TestClient:TestSecret -d 'grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA'

A successful token request will return a standard access token in JSON format:


If the server is configured to always issue a new refresh token, then a refresh token will be returned with this response as well:

Fork me on GitHub