!!! Overview
Refresh [Tokens] are a [Credential] in the form of a [Sender Constrained Token] issued to the [OAuth Client] by the [Authorization Server] that is used to obtain a new [Access Tokens].  

You may need a new [Access Tokens] because:
* expired as they short-lived
* becomes invalid
* a change in the [OAuth Scope] is required (ie fewer permissions than authorized by the [Resource Owner]).  

Issuing a [{$pagename}] is [OPTIONAL] at the discretion of the [Authorization Server].  

If the [Authorization Server] issues a [{$pagename}], it is included when issuing an [Access Token]

A [{$pagename}] is a string representing the [authorization] granted to the [OAuth Client] by the [Resource Owner].  

The [{$pagename}] is usually opaque to the [OAuth Client].

The [{$pagename}] denotes an identifier used to retrieve the [Authorization] information. 

[{$pagename}] usually require a check against the [Authorization Server].

Unlike [Access Tokens], [{$pagename}]s are intended for use only with [Authorization Servers] and are __never__ sent to [Resource Servers].

!! Obtaining [{$pagename}]
Although the [OAuth 2.0] specifications do not appear to define how to obtain a [{$pagename}], the industry seems to have adopted that an [OAuth Scope] of [offline_access] within the [Authorization Request] or [Authentication Request]  using an [Authorization Code Grant] may optionally get a [{$pagename}].

[OAuth 2.0] specifications specifically state: 
* [Implicit Grant] "does not support the issuance of [{$pagename}]" and "The [Authorization Server] [MUST NOT] issue a [{$pagename}]."
* [Resource Owner Password Credentials Grant] "Optional Refresh Token"
* [Client Credentials Grant] - "A refresh token [SHOULD NOT] be included."
* Authorization servers [MAY] issue refresh tokens to [web] [application] clients and [native application] clients.
* [OpenID Connect] defines [offline_access]

!! Security considerations
[{$pagename}] are long-lived. This means when a [OAuth Client] gets a [{$pagename}] from an [Authorization Server], the [{$pagename}] must be stored securely to keep it from being used by potential attackers. If a [{$pagename}] is leaked, it could be used to obtain new [Access Tokens] (and access protected resources) until it is either blacklisted or it expires (which may take a long time). 

[{$pagename}] must be issued to a single authenticated [OAuth Client] to prevent use of leaked tokens by other parties. 

!! Using [{$pagename}][1]
This is a simple [example] of how [{$pagename}] can be obtained and used. Using a simple CURL command as the client.

The [Token_endpoint] could be (/oauth/token), which handles issuing of all types of grants (access and refresh tokens).

Assuming there is a [Resource Owner] ‘test‘ with password ‘test‘ and a [OAuth Client] ‘testclient‘ with a client secret ‘secret‘, a sample [Access Token Request] of a new [Access Token]/[{$pagename}] pair could be the following:
%%prettify 
{{{
$ curl -X POST -H 'Authorization: Basic dGVzdGNsaWVudDpzZWNyZXQ=' -d 'grant_type=password&username=test&password=test' localhost:3000/oauth/token
{
    "token_type":"bearer",
    "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiVlx1MDAxNcKbwoNUwoonbFPCu8KhwrYiLCJpYXQiOjE0NDQyNjI1NDMsImV4cCI6MTQ0NDI2MjU2M30.MldruS1PvZaRZIJR4legQaauQ3_DYKxxP2rFnD37Ip4",
    "expires_in":20,
    "refresh_token":"fdb8fdbecf1d03ce5e6125c067733c0d51de209c"
}
}}} /%
The authorization header contains the client id and secret encoded as BASE64 (testclient:secret).

When a new [Access Token] is required, you can use the [{$pagename}] to get a new [Access Token] by using the [token_endpoint] as shown below:
%%prettify 
{{{
$ curl -X POST -H 'Authorization: Basic dGVzdGNsaWVudDpzZWNyZXQ=' -d 'refresh_token=fdb8fdbecf1d03ce5e6125c067733c0d51de209c&grant_type=refresh_token' localhost:3000/oauth/token
{
    "token_type":"bearer",
    "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiVlx1MDAxNcKbwoNUwoonbFPCu8KhwrYiLCJpYXQiOjE0NDQyNjI4NjYsImV4cCI6MTQ0NDI2Mjg4Nn0.Dww7TC-d0teDAgsmKHw7bhF2THNichsE6rVJq9xu_2s",
    "expires_in":20,
    "refresh_token":"7fd15938c823cf58e78019bea2af142f9449696a"
}
}}} /%
Notice in the above command, that the [grant_type] is the "refresh_token" and not the [grant_type] used in the original [Access Token Request]. As the result of this command a new Access Token is returned.

!! Offline Access

!! More Information
There might be more information for this subject on one of the following:
[{ReferringPagesPlugin before='*' after='\n' }]
----
* [#1] - [Using Refresh Tokens|https://auth0.com/learn/refresh-tokens//|target='_blank'] - based on information obtained 2016-05-15-