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

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

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

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
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
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int

Number of results returned.

offset
Int

Number of results skipped.

withTotal
Boolean

Calculate total number of results.

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
The parameter can be passed multiple times.
Request Body:ApiClientDraft
Response:
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:
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/api-clients/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Developer Center
HTTP APIGraphQL APIPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & ExportSUNRISE Starter FrontendsTutorialsFAQ
Copyright © 2022 commercetools