The client credentials grant flow

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

The access token retrieved from this process is called an Application access token. For details on token types and more, see Access token types.

Subtopics

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:

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:

Flow for generating an Application token
 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:

OAuth token-request endpoints

Environment

Endpoint (HTTP method + URL)

Sandbox POST https://api.sandbox.ebay.com/identity/v1/oauth2/token
Production POST https://api.ebay.com/identity/v1/oauth2/token

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 Specifying OAuth scopes.

Note: With Application access tokens, the user has an inherent authorization to make eBay calls. Because of this unique privilege, eBay often performs a special vetting process on applications that make use of Application tokens.

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

Tip: The example on this page targets the Sandbox. Be sure to update the endpoint shown if you want to target the Production environment.

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'

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 Authorize HTTP header, as described in HTTP request headers.

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.

Important! Access tokens must be treated as confidential and must not be shared or exposed publicly. For best performance and security, applications should store this token in a static variable and re-use the token while it is valid.