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