Skip to page content.

OAuth 2.0

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 Basic Authentication.

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://oauth.oclc.org/token

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
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 Basic Authentication

Example Request

POST /token?grant_type=client_credentials&scope=configPlatform%20context:128807 
HTTP/1.1
Host: https://oauth.oclc.org
Accept: application/json
Authorization: Basic RWQ0N1BNZFRXT01ENElPc2szbnFLUFlGS29Kb0dXYWtHVURUQnJsOHM5SVdZTnlnYWlsUXNZSThvZkd0M2RxM3JMbzBia0ZnUldSTjZvTUo6eG9XN0ZtQzZqS2N0THNPV3Y2Q3pPZz09
Content-Length: 0

Example Response

{
  "access_token":"tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW",
  "token_type":"bearer",
  "expires_in":"3599",
  "principalID":"",
  "principalIDNS":"",
  "scopes":"configPlatform context: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
scopes List of scopes the token is issued for
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

Clients can make a request to most web services by sending an access token via 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?

Machine to Machine Applications

Typically, you use this flow if you have a non-interactive application that requires access to an API. Examples include command-line tools, daemons, IoT devices, bash scripts or services running on your back-end.

In contrast to the other OAuth flows used to obtain access tokens, this flow does not require a client a user login and the client does not redirect a user's web browser to a username/password login process.