Documentation

Developer settings

Elevate, May 20-22-2025, Miami Beach, Florida

Manage API Clients and enable Messages in commercetools Composable Commerce.

API Clients

This feature is for developer use only. You can also manage API Clients using the API. For more information, see API Clients.
commercetools Composable Commerce API Clients use OAuth 2.0 for authorization. You can grant one or more scopes to API Clients that give access to specific parts of your Project's data. For more information, see Authorization and Scopes.

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 Project is 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 Manage token requests.

Create an API Client

After creating an API Client, the Merchant Center displays certain important information only once. You should save this information in a safe place.

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.
    Scopes granted to API Clients to access specific parts of a Project's data.

    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.

  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. Access token obtained using cURL.

Delete an API Client

Exercise caution as it is possible to delete an API Client that is in use.

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.

Project messages

Messages represent changes or actions performed on resources in your Project, such as Orders or Products. You can use Messages to get notified about changes in your Project. For example, when Customers are created a Customer Created Message is generated. After receiving this message, you can send a verification email to the new Customer.
We recommend using Subscriptions to receive the Messages on the message queue of your choice. If you want to query Messages via the API, you must first enable the feature in Settings > Developer settings > Project messages. This option is off by default to improve performance, and should be off if you use Subscriptions.

GraphQL Explorer

The GraphQL Explorer lets you make GraphQL calls and view the documentation of GraphQL types and fields. It is useful for experimenting with GraphQL API features and making ad hoc updates to resources.

To access the GraphQL Explorer from the Merchant Center main menu, go to Settings > Developer settings, then click the GraphQL Explorer tab.
To access the GraphQL Explorer, the user's team must have the View all: Developer settings permission. In addition, to view or edit specific resources using the GraphQL Explorer, the team must also have the necessary resource permissions.

API Playgrounds

The API Playgrounds let you send requests to the HTTP API and Import API endpoints. They are useful for experimenting with API features and making ad hoc updates to resources.
To access the API Playgrounds from the Merchant Center main menu, go to Settings > Developer settings, then click either the HTTP API Playground tab, or the Import API Playground tab.
To access the API Playgrounds, the user's team must have the View all: Developer settings permission. In addition, to view or edit specific resources using the API Playground, the team must also have the necessary resource permissions.