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://authn.sd00.worldcat.org/oauth2/accessToken

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 the HMAC Signature documentation.

Refresh Token Requests from native mobile clients do not need to be signed using the HMAC Signature documentation. However, the WSkey used to obtain the Refresh token does need to be sent in the request

Example Request - Web Clients

POST /oauth2/accessToken?grant_type=refresh_token&refresh_token=rt_4393983 HTTP/1.1
Host: https://authn.sd00.worldcat.org
Accept: application/json
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1 
clientId="jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa ",
timestamp="1361911277", nonce="5368c00b", signature="CG+ENonHuWQ657pKGfpkFHb0MZgz7SWlL+A4902O5bA="
Content-Length: 0

Example Request - Mobile Clients

POST /oauth2/accessToken?grant_type=refresh_token&refresh_token=rt_4393983
&client_id=jdfRzYZbLc8HZXFByyyLGrUqTOOmkJOAPi4tAN0E7xI3hgE2xDgwJ7YPtkwM6W3ol5yz0d0JHgE1G2Wa 
HTTP/1.1
Host: https://authn.sd00.worldcat.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.