The client credentials grant flow

This topic describes how to mint OAuth access tokens using the client credentials grant flow.

The access token retrieved from this process is called an Application access token.

OAuth client libraries

The processes in this topic describe how to manually get OAuth tokens. To help with this process, eBay offers several client libraries that you can use to quickly implement the minting of OAuth tokens in your applications:

• OAuth client library for Android
• OAuth client library for C#
• OAuth client library for Java
• OAuth client library for Node.js
• OAuth client library for Python

Sequence for getting and using an Application access token

The following sequence diagram outlines the client credentials grant flow, where an Application access token is minted, then used in an API request:

 Sequence diagram for generating an Application access token

Configuring the request

You need to configure three parts of a client credentials grant request:

• The target endpoint
• The HTTP request headers
• The request payload

Setting the target endpoint

The endpoint you use depends on the environment you're targeting:

Configuring the HTTP request headers

Set the following HTTP request headers:

• Content-Type – Must be set to: application/x-www-form-urlencoded

• Authorization – The word "Basic " followed by your Base64-encoded OAuth credentials (<client_id>:<client_secret>).

  For details, see Generating your Base64-encoded credentials.

Configuring the request payload

Format the payload of your POST request with the following values:

• Set grant_type to client_credentials.

• Set scope to the URL-encoded space-separated list of the scopes needed for the interfaces you call with the access token.

  For details, see Using OAuth to access eBay APIs.

The client credentials grant request

The client credentials grant is a single request that mints a new Application access token. Use the token to make requests to API methods that match the scopes configured into the access token.

Configure your request using the following call specifics:

  HTTP method:   POST
  URL (Sandbox): https://api.sandbox.ebay.com/identity/v1/oauth2/token

  HTTP headers:
    Content-Type = application/x-www-form-urlencoded
    Authorization = Basic <B64-encoded-oauth-credentials>

  Request body:
    grant_type=client_credentials
    scope=<scopeList>   // a URL-encoded string of space-separated scopes
    

Example cURL request

The following command shows how to configure the client credentials grant request with cURL:

curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic UkVTVFRlc3...wZi1hOGZhLTI4MmY=' \
  -d 'grant_type=client_credentials&scope=https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope %20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fbuy.item.bulk'

Response containing the Application access token

When you issue a client credentials grant request, eBay returns a JSON object that contains an Application access token, as shown in this response:

  {
    "access_token": "v^1.1#i^1#p^1#r^0#I^3#f^0#t^H4s ... wu67e3xAhskz4DAAA",
    "expires_in": 7200,
    "token_type": "Application Access Token"
  }

To use an access token to authorize an API request, pass the token value in the Authorization HTTP header.

In the above example, the expires_in element is set to 7,200 seconds, meaning this token is valid for two hours from the time it was generated. For continued access after the token expires, you must mint a new token.