API Clients

Best practices

We recommend giving an API Client the minimum scope required. For example, when creating an API Client to update Product information, give it scopes only for Products. This ensures that your commercetools Project and 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 programmatically. For more information, see Managing token requests.

Create an API Client

To create an API Client, do the following:

1. In the Merchant Center main menu, go to Settings > Developer settings.

2. Click Create New API Client.

3. In the Name field, enter a name for your API Client. The API Client name must be unique and differ from other names.

4. Select individual permissions (scopes) for the API Client, or a template (with pre-selected scopes) from the drop-down.

   Some scopes automatically include a related scope. For example, if you select the Manage Customers scope, the View Customers scope is automatically selected. For more information, see Scopes.

   

   You can set scopes only when creating an API Client.

5. If needed, add scopes for specific Stores in your Project. For more information, see Create an API Client with Store scopes.

6. Click Create API Client.

7. Copy client_id, secret, scope, API URL, and Auth URL to a safe location as they are displayed only once. Alternatively, copy or download one of the language-specific environment presets. We recommend copying at least the cURL version for all API Clients to generate an access token.

Create an API Client with Store scopes

Stores assign Team permissions and add API Client scopes to specific subsets of your data. Store scopes are useful for large organizations managing data access across regions and other selling contexts. For example, if you create an API Client with the Manage Orders scope for a store Germany, the client can only view and edit orders in the Germany store, even if other orders exist in the Project.

To create an API Client with Stores scopes, do the following:

1. In the Merchant Center main menu, go to Settings > Developer settings.

2. Click Create New API Client.

3. In the Name field, enter a name for your API Client. The API Client name must be unique and differ from other names.

4. Select individual permissions (scopes) for the API Client, or a template (with pre-selected scopes) from the drop-down.

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

5. Click Add scopes for store(s).

6. Select a Store from the list of Stores defined.

   Stores must be created using HTTP or GraphQL APIs. For more information, see Stores.

7. Select individual permissions (scopes) for the API Client.

8. Click Create API Client.

9. Copy client_id, secret, scope, API URL, and Auth URL to a safe location as they are displayed only once. Alternatively, copy or download one of the language-specific environment presets. We recommend copying at least the cURL version for all API Clients to generate an access token.

Create an API Client access token using cURL

For production use, we do not recommend using cURL to generate and refresh access tokens for an API Client. However, it can be convenient when exploring an API, for example, retrieving the API Client's access token for use with our Postman collection.

After you create an API Client, do the following:

1. Copy the cURL request (similar to the below example) and paste it into a command-line prompt, and press Enter.

   curl https://auth.{region}.commercetools.com/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.

2. Copy and save the access_token displayed on the next line of the cURL request.

Delete an API Client

To delete an API Client, do the following:

1. In the Merchant Center main menu, go to Settings > Developer settings.
2. Select the respective API Client and click the delete icon.
3. Click Confirm in the dialog.