API Clients

You can create and delete API Clients for use with the commercetools platform in the Merchant Center.

Note: This feature is for developer use only. You can also manage API Clients using the API; see API Clients for more information.

You can create and delete API Clients for use with the commercetools platform in the Merchant Center.

commercetools API clients use OAuth2 for authorization. Clients are granted one or more API scopes. The scopes allow them to access specific parts of your commercetools project’s data.

For more information see:

Best practices

We recommend that you give a client the minimum scope required. For example, when creating an API client to update product information, only give it scopes for products. This ensures your project and the platform are as secure as possible.

For most production use cases, we recommend using an SDK to manage your API Clients instead of the Merchant Center. This allows you to manage token requests programatically. For more information, see Managing Token Requests.

Creating an API Client

Warning: After creating an API Client, the Merchant Center displays certain important information only once. Copy this information down to a safe place!

  1. In the Merchant Center main menu, navigate to Settings > Developer Settings
  2. Click the Create New API Client button.
  3. In the Name field, enter a name for your API Client. Each API Client you create must have a unique name.
  4. Select individual permissions (scopes) for the API Client, or use the drop-down list to select a template.

select-scopes

Warning: You can only set an API Client’s scopes when you create the client.

Note: Some scopes imply, or automatically include, a related scope. For example, if you check the Manage Customers scope, it also adds the View Customers scope. For a list of all scopes and what they do, see Scopes.

  1. If needed, add scopes for specific Stores in your project. For more information, see Creating an API Client with store scopes.
  2. Click Create API Client.
  3. Copy the following information to a safe location:
    • client_id, secret, scope, API URL, Auth URL.

or:

  • Copy or download one of language-specific the environment presets. We recommend copying at least the cURL version for all API Clients to generate an access token.

Creating an API Client with store scopes

Stores assign team permissions and add API Client scopes to specific subsets of your data. For example, if you create an API Client with the Manage Orders scope for the store “USA”, the client can only see and edit orders in the USA store, even if other orders exist in the project.

Stores scopes are particularly useful for large organizations managing data access across regions and other selling contexts.

To create an API Client with stores scopes:

  1. Follow steps 1-4 of Creating an API Client.

    Note: You do not need to add general scopes for an API Client.

  2. After selecting the scopes for your client, click the Add scopes for store(s) button.
  3. In the dropdown, select a store to create a scope for.

    Note: You must create the stores using the HTTP or GraphQL APIs. For more information, see Stores.

  4. Select individual permissions (scopes) for the API Client.
  5. Click Create API Client.
  6. Copy the following information to a safe location:
    • client_id, secret, scope, API URL, Auth URL.

or:

  • Copy or download one of language-specific the environment presets. We recommend copying at least the cURL version for all API Clients to generate an access token.

Creating an API Client access token using cURL

We do not recommend using cURL to generate and refresh access tokens for an API Client for production use. When exploring the API, however, it’s convenient. You can use cURL to retrieve the API Client’s access token for use with our Postman collection, for example.

To create an API Client access token using cURL:

  1. Create an API Client using the steps described above, and copy the cURL request once the client is created. It should look something like this:
      curl https://auth.sphere.io/oauth/token \
      --basic --user "ZW-i2w6tu-61tSlSbie6Z41c:oqFJEK1OhPtLphtgxIZeOjzKs9dxMQv8" \
      -X POST \
      -d "grant_type=client_credentials&scope=manage_customers:{projectKey}"
    

Where {projectKey} is your project key.

  1. Copy and paste this into a command line prompt and press Enter. The next line will include an access_token.

cli-curl

  1. From this, copy the access_token’s value and save it.

Deleting an API Client

Note: You can delete an API Client that is currently in use! Proceed with caution.

  1. In the Merchant Center main menu, navigate to Settings > Developer Settings
  2. Find the API Client you want to delete.
  3. Click the trash-icon icon.