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

APIClientDraft

ApiClientPagedQueryResponse

APIClient

`id` String	Unique ID of the API client. This is the OAuth2 `client_id` that can be used to obtain an access token.
`createdAt` DateTime	Date and time (UTC) the API Client was initially created.
`name` String	Name of the API Client.
`scope` String	Whitespace-separated list of OAuth scopes that can be used when obtaining an access token.
`secret` String	Only shown once in the response of creating the API Client. This is the OAuth2 `client_secret` that can be used to obtain an access token.
`lastUsedAt` Date	Date of the last day this API Client was used to obtain an access token.
`deleteAt` DateTime	If set, the client will be deleted on (or shortly after) this point in time.

APIClientDraft

`name` String	Name of the API Client.
`scope` String	Whitespace-separated list of OAuth scopes that can be used when obtaining an access token.
`deleteDaysAfterCreation` Int	If set, the client will be deleted after the specified amount of days.

ApiClientPagedQueryResponse

PagedQueryResult with results containing an array of APIClient.

`limit` Int	Number of results requested in the query request.
`offset` Int	Offset supplied by the client or server default. It is the number of elements skipped, not a page number.
`count` Int	Actual number of results returned.
`total` Int	Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter `withTotal=false`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`results` Array of ApiClient	API Clients matching the query.

Get API Client

GET

https://api.{region}.commercetools.com/{projectKey}/api-clients/{id}

OAuth 2.0 Scopes:

view_api_clients:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the API Client.

Response:

200ApiClient

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/api-clients/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Query API Clients

GET

https://api.{region}.commercetools.com/{projectKey}/api-clients

OAuth 2.0 Scopes:

view_api_clients:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

`where` QueryPredicate	The parameter can be passed multiple times.
`/^var[.][a-zA-Z0-9]+$/` Any string parameter matching this regular expression	Predicate parameter values. The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results returned.
`offset` Int	Number of results skipped.
`withTotal` Boolean	Controls the calculation of the total number of query results. Set to `false` to improve query performance when the `total` is not needed.

Response:

200ApiClientPagedQueryResponse

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/api-clients -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create API Client

POST

https://api.{region}.commercetools.com/{projectKey}/api-clients

OAuth 2.0 Scopes:

manage_api_clients:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:ApiClientDraft

Response:

201ApiClient

Request Example:cURL

curl -X POST https://api.{region}.commercetools.com/{projectKey}/api-clients -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "name" : "api-client-name",
  "scope" : "view_products"
}
DATA

Delete API Client

DELETE

https://api.{region}.commercetools.com/{projectKey}/api-clients/{id}

OAuth 2.0 Scopes:

manage_api_clients:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the API Client.

Response:

200ApiClient

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/api-clients/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'