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

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

Requests will need to be signed using the HMAC Signature documentation.

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.

Example Request

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

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.

We are a worldwide library cooperative, owned, governed and sustained by members since 1967. Our public purpose is a statement of commitment to each other—that we will work together to improve access to the information held in libraries around the globe, and find ways to reduce costs for libraries through collaboration. Learn more »