API Clients

View, create and delete API clients

The commercetools platform depends on OAuth2 for authorization. API clients can either be created in the Merchant Center, or with the API documented on this page. The API is especially useful for Infrastructure-as-Code tooling, as well as for regularly rotating your API secrets.

Due to the sensitive nature of this API, it can not be used with the manage_project:{projectKey} scope, but only with manage_api_clients:{projectKey}.

Once an API client has been created, it can not be changed. The secret is only visible in the response when creating the API Client.

Representations

APIClient

  • id - String
    The unique ID of the API client. This is the OAuth2 client_id and can be used to obtain a token.
  • name - String
  • scope - String
    A whitespace separated list of the OAuth scopes. This is the OAuth2 scope and can be used to obtain a token.
  • createdAt - DateTime - Optional
  • lastUsedAt - Date - Optional
    The last day this API Client was used to obtain a token.
  • secret - String - Optional
    The secret is only shown once in the response of creating the API Client. This is the OAuth2 client_secret and can be used to obtain a token.

APIClientDraft

  • name - String
  • scope - String - A whitespace separated list of the OAuth scopes

Get an API Client by ID

Endpoint: /{projectKey}/api-clients/{id}
Method: GET
OAuth2 Scopes: view_api_clients:{projectKey}
Response Representation: APIClient

Query API Clients

Endpoint: /{projectKey}/api-clients
Method: GET
OAuth2 Scopes: view_api_clients:{projectKey}
Response Representation: PagedQueryResult with the results array of API Client
Query Parameters:

Create an API Client

Endpoint: /{projectKey}/api-clients
Method: POST
OAuth2 Scopes: manage_api_clients:{projectKey}
Request Representation: API Client Draft
Response Representation: API Client

Delete an API Client

Endpoint: /{projectKey}/api-clients/{id}
Method: DELETE
OAuth2 Scopes: manage_api_clients:{projectKey}
Response Representation: API Client