About
When an access token expires, developers can use an optional refresh token to request a new access token without having to ask the user to enter their credentials again.
Refresh tokens are credentials used to obtain:
- access tokens when the current access token becomes invalid or expires,
- additional access tokens with identical or narrower scope (access token may have a shorter lifetime and fewer permissions than authorized by the resource owner).
Structure
A refresh token is a string representing the authorization granted to the client by the resource owner.
The string is usually opaque to the client.
The token denotes an identifier used to retrieve the authorization information.
Unlike access tokens, refresh tokens are intended for use only with token endpoint (authorization servers component) and are never sent to resource servers.
Management
Creation
Refresh tokens are issued to the client by the token endpoint (authorization server component).
Issuing a refresh token is optional at the discretion of the authorization server. If the token endpoint (authorization server component) issues a refresh token, it is included when issuing an access token
Flow
where:
Get the first refresh token
- (A) The client requests an access token (and refresh token) by authenticating with the token endpoint (authorization server component) and presenting an authorization grant.
- (B) The token endpoint (authorization server component) authenticates the client and validates the authorization grant, and if valid, issues an access token and a refresh token.
Client gets resources until the access token is valid
- (C) The client makes a protected resource request to the resource server by presenting the access token.
- The resource server validates the access token, and
- if valid, (D) serves the request.
- else (D') returns an invalid token error
Client asks for new access token with refresh token
- (E) The client requests a new access token by authenticating with the token endpoint (authorization server component) and presenting the refresh token. The client authentication requirements are based on the client type and on the authorization server policies.
- (F) The authorization server authenticates the client and validates the refresh token, and if valid, issues a new access token (and, optionally, a new refresh token).