Documentation

API Clients

View, create, and delete API clients

The commercetools platform depends on OAuth 2.0 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 frequently 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 OAuth 2.0 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 OAuth 2.0 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 OAuth 2.0 client_secret and can be used to obtain a token.
  • deleteAt - DateTime - Optional
    If set, the client will be deleted at that time or soon afterwards.

APIClientDraft

  • name - String
  • scope - String - A whitespace separated list of the OAuth scopes
  • deleteDaysAfterCreation - Int - Optional
    If set, the client will be deleted after the specified amount of days.

Get an API Client by ID

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

Query API Clients

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

Create an API Client

Endpoint: /{projectKey}/api-clients
Method: POST
OAuth 2.0 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
OAuth 2.0 Scopes: manage_api_clients:{projectKey}
Response Representation: API Client