Refresh Token
A Refresh token is a string that represents an authorization that was granted to a client to use a particular set of web services on behalf of a user to access data for a particular institution. Refresh Tokens are issued to the client by OCLC's Authorization Server upon request of an Access Token. Refresh Token are typically longer lived than Access Tokens and used to request a new Access Token without forcing user authentication. Unlike Access Tokens, Refresh Tokens are only used with the Authorization Server and are never sent to a web service.
Obtaining a Refresh Token
Our Explicit Authorization Code flow allows clients to obtain a Refresh Token when a request for an Access Token is made. Refresh Tokens last for a specific amount of time, typically 1 day. To request a Refresh Token as part of the request for an access token, the client needs to specify refresh_token as one of the scopes being requested when obtaining the authorization code.
If a Refresh Token is requested then the following fields are also returned in the response:
| Name | Description |
|---|---|
| refresh_token | The value of the Refresh Token. This is what the client will need to send if obtaining a new Access Token via a Refresh Token |
| refresh_token_expires_in | Number of seconds in which the Refresh Token will expire |
| refresh_token_expires_at | Timestamp when the Refresh Token will expire. |
Using a Refresh Token - Explicit Flow
To use a refresh token to get a new Access Token a client needs to make a request to the Access Token endpoint of the Authorization server.
Base URL: https://oauth.oclc.org/token
Refresh Token Parameters
| Name | Description | Required? | Expected / Sample Values |
|---|---|---|---|
| grant_type | The type of grant being used to obtain the access token. | Yes | refresh_token |
| refresh_token | The value of the refresh token being used to obtain a new access token |
Yes | rt_4393983 |
| client_id | The WSKey being used by the client | No, required for Mobile Client requests |
Refresh Token Requests from Server-side clients will need to be signed using Basic Authenication
Refresh Token Requests from native mobile clients do not need to be signed using Basic Authentication. However, the WSkey used to obtain the Refresh token does need to be sent in the request
Example Request - Web Clients
POST /token?grant_type=refresh_token&refresh_token=rt_4393983 HTTP/1.1 Host: https://oauth.oclc.org Accept: application/json Authorization: Basic RWQ0N1BNZFRXT01ENElPc2szbnFLUFlGS29Kb0dXYWtHVURUQnJsOHM5SVdZTnlnYWlsUXNZSThvZkd0M2RxM3JMbzBia0ZnUldSTjZvTUo6eG9XN0ZtQzZqS2N0THNPV3Y2Q3pPZz09Content-Length: 0
Example Request - Mobile Clients
POST /token?grant_type=refresh_token&refresh_token=rt_4393983 &client_id=jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa HTTP/1.1 Host: https://oauth.oclc.org Accept: application/json
If the request for an Access Token is successful then the Authorization Server will return a JSON response that contains a variety of information about the AccessToken to the client.
You cannot get a new refresh token using a refresh token. Getting a new refresh token requires the client to request an Access Token using one of the other flows.
Why would I use a Refresh Token?
Refresh Tokens are useful because they allow applications to get new Access Tokens without forcing users to login to the system repeatedly. Typically our Access Tokens last for 20 minutes. This means after 20 minutes the user would have to re-authenticate in order to continue to use the application interacting with the web service. This may be undesirable if the user is used to a scenario where they are logged into the system until they explicit log out or close their browser window. To deal with this scenario, we have implemented Refresh Tokens which allow the application to request a new Access Token, "behind the scenes", and maintain the user's session beyond the length of the life of the Access Token.