Client Credentials Grant

How Does it Work?

Using the Client Credentials Grant OAuth pattern, a client obtains an access token by making a single HTTP request to OCLC's Authorization Server. Using its WSKey and secret, a client requests an Access Token for one or more web services from OCLC's WSKey server. The HTTP request is validated by including a digital signature using our HMAC Signature pattern.

After successfully requesting a token using this pattern, the client can use it like a session token to make subsequent requests to web services until it expires.

Step 1: Request an Access Token

Base URL: https://authn.sd00.worldcat.org/oauth2/accessToken

Client Credential Grant Parameters

Name Description Required? Expected / Sample Values
grant_type The grant type designates the type of OAuth grant the client is requesting. This value is fixed for this pattern.
Yes client_credentials
authenticatingInstitutionId The WorldCat Registry ID for the institution responsible for authenticating a user when principal information is included on the request. Yes 128807
contextInstitutionId The WorldCat Registry ID for the institution whose data the client is requesting to access or modify.
Yes 128807
scope A space separated list of the services for which the client is request access.
Yes
  • WorldCatMetadataAPI
  • WMS_ACQ%20WMS_VIC

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

Example Request

POST /oauth2/accessToken?grant_type=client_credentials&authenticatingInstitutionId=128807
&contextInstitutionId=128807&scope=configPlatform HTTP/1.1
Host: https://authn.sd00.worldcat.org
Accept: application/json
Authorization: http://www.worldcat.org/wskey/v2/hmac/v1
clientId="LXAjXFWEtkA5MHrbpu2YElhMypGHXEPORjp2pTt4E2GwZ1Bx0RhA7YyQutyuSXX5AAjJv3aYH0FWirC6",
timestamp="1361378384", nonce="5e98cf0c", signature="s0oPalwN4/J0bsKj9RTkc/BaD9oxbrsA+jOOw/G/Kc4="
Content-Length: 0

Example Response

{
  "access_token":"tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW",
  "token_type":"bearer",
  "expires_in":"3599",
  "principalID":"cpe4c7f6-f5a4-41fa-35c9-9d59443f544p",
  "principalIDNS":"urn:oclc:platform:128807",
  "contextInstitutionId": "128807",
  "expires_at": "2013-08-23 18:45:29Z"
}

A successful response for an Access Token will return a JSON document with the following fields:

Name Description
token_type Type of token. In our implementation this will always be "bearer"
access_token The value of the Access Token. This is what the client will need to send to the web service.
expires_in Number of seconds in which the Access Token will expire
principalID The user id of the user who logged in
principalIDNS Principal identity namespace the user's principalID is in
contextInstitutionId WorldCat Registry institution ID of the institution's data the Access Token has rights to access
expires_at Timestamp when the Access Token will expire.

Step 2: Use the Access Token with an OCLC Service

As explained in the Access Token documentation, clients can make a request to most web services by sending an access token on the HTTP Authorization request header. A request header with an access token looks like the following:

Authorization: Bearer tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW

Why would I use this flow?

This flow is designed for two primary use cases.

1. User Identity Verified by the Client

This mechanism for obtaining an access token does not require a client to have a user login. In contrast to the other OAuth patterns used to obtain access tokens, Explicit Authorization and User Agent, the client does not send a user's web browser through a username/password login process.

Some integration partners can establish a user session by working with OCLC to configure SAML integration. In this scenario, a client has already authenticated a user and is in possession of a user session and identity that is required by some OCLC's APIs and web services. The Client Credentials Grant pattern can then be used to obtain a token to gain access to a given API.

For this use case, when making the request to the WSKey server to obtain the token, the client should send principal information via the HMAC signature on the HTTP Authorization header:

Authorization: http://www.worldcat.org/wskey/v2/hmac/v1
clientId="LXAjXFWEtkA5MHrbpu2YElhMypGHXEPORjp2pTt4E2GwZ1Bx0RhA7YyQutyuSXX5AAjJv3aYH0FWirC6",
timestamp="1361378384", 
nonce="5e98cf0c", 
signature="s0oPalwN4/J0bsKj9RTkc/BaD9oxbrsA+jOOw/G/Kc4=", 
principalID="{principal-ID}", 
principalIDNS="{principal-ID-namespace}"

2. Web Service Doesn't Require User Identity

Not all web services validate user identity. If you are interacting with a web service that doesn't require user identity then you can generate an Access Token which is not tied to a specific user and use that Access Token to authenticate to the web service.

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 »