API Clients

View, create, and delete API Clients

The commercetools Composable Commerce APIs 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.

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

This API allows you to configure the expiration times of OAuth tokens for your API Client. If you want to set expiration times different to the default values shown below, you need to use this API instead of the Merchant Center for creating your API Client.

Token typeDefaultMinimumMaximum
access token48 hours1 hour7 days
refresh token200 days30 seconds1 year

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}.

Representations

APIClient

id
String

The OAuth2 client_id that can be used to obtain an access token.

createdAt

Date and time (UTC) the APIClient was initially created at.

name
String

Name of the APIClient.

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 APIClient. This is the OAuth2 client_secret that can be used to obtain an access token.

lastUsedAt
Date

Date of the last day this APIClient was used to obtain an access token.

deleteAt

If set, the Client will be deleted on (or shortly after) this point in time.

accessTokenValiditySeconds
Int

Expiration time in seconds for each access token obtained by the APIClient. Only present when set with the APIClientDraft. If not present the default value applies.

Default: 172800Minimum: 3 600Maximum: 604 800
refreshTokenValiditySeconds
Int

Inactivity expiration time in seconds for each refresh token obtained by the APIClient. Only present when set with the APIClientDraft. If not present the default value applies.

Default: 17280000Minimum: 30Maximum: 31 536 000

APIClientDraft

name
String

Name of the APIClient.

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.

accessTokenValiditySeconds
Int

Expiration time in seconds for each access token obtained by the APIClient. If not set the default value applies.

Default: 172800Minimum: 3 600Maximum: 604 800
refreshTokenValiditySeconds
Int

Inactivity expiration time in seconds for each refresh token obtained by the APIClient. The expiration time for refresh tokens is restarted each time the token is used. If not set the default value applies.

Default: 17280000Minimum: 30Maximum: 31 536 000

ApiClientPagedQueryResponse

PagedQueryResult with results containing an array of APIClient.

limit
Int

Number of results requested.

offset
Int

Number of elements skipped.

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

APIClients 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
offset
Int

Number of elements 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
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",
"accessTokenValiditySeconds" : 3600,
"refreshTokenValiditySeconds" : 31536000
}
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}'