This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

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.

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
createdAt

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

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
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:
200ApiClientasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/api-clients/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ApiClientjson
{
"id": "api-client-id",
"name": "api-client-name",
"scope": "view_products:{projectKey}",
"createdAt": "2018-01-01T00:00:00.001Z",
"lastUsedAt": "2017-09-10",
"accessTokenValiditySeconds": 3600,
"refreshTokenValiditySeconds": 31536000
}

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:
200ApiClientPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/api-clients -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ApiClientPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "api-client-id",
"name": "api-client-name",
"scope": "view_products:{projectKey}",
"createdAt": "2018-01-01T00:00:00.001Z",
"lastUsedAt": "2017-09-10",
"accessTokenValiditySeconds": 3600,
"refreshTokenValiditySeconds": 31536000
}
]
}

Check if API Client exists

Check if API Client exists by ID

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

Checks if an API Client exists for a given id. Returns a 200 OK status if the API Client exists or a 404 Not Found otherwise.

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:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/api-clients/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if API Client exists by Query Predicate

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

Checks if an API Client exists for a given Query Predicate. Returns a 200 OK status if any API Clients match the Query Predicate or a 404 Not Found otherwise.

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

Query Predicates on API Clients are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head 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:ApiClientDraftasapplication/json
Response:
201ApiClientasapplication/json
Request Example:cURL
curl 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:{projectKey}",
"accessTokenValiditySeconds" : 3600,
"refreshTokenValiditySeconds" : 31536000
}
DATA
201 Response Example: ApiClientjson
{
"secret": "secret-passphrase",
"id": "api-client-id",
"name": "api-client-name",
"scope": "view_products:{projectKey}",
"createdAt": "2018-01-01T00:00:00.001Z",
"accessTokenValiditySeconds": 3600,
"refreshTokenValiditySeconds": 31536000
}

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:
200ApiClientasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/api-clients/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ApiClientjson
{
"id": "api-client-id",
"name": "api-client-name",
"scope": "view_products:{projectKey}",
"createdAt": "2018-01-01T00:00:00.001Z",
"lastUsedAt": "2017-09-10",
"accessTokenValiditySeconds": 3600,
"refreshTokenValiditySeconds": 31536000
}