API Clients

View, create, and delete API Clients

To interact with commercetools Composable Commerce APIs, use an API Client with dedicated scopes that allow read or write access to resources within your project.

You must create your first API Client in the Merchant Center. After that, you can create additional clients in the Merchant Center or through the API Clients API. You can use the API Clients endpoints only from an authorized API Client.

The API Clients API is especially useful for Infrastructure as Code (IaC) tooling and for frequently rotating your API secrets.

commercetools Composable Commerce APIs use OAuth 2.0 for authorization.

Once you create an API Client, you cannot change it. The secret is visible only 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 type	Default	Minimum	Maximum
access token	48 hours	1 hour	7 days
refresh token	200 days	30 seconds	1 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}.

Learn more about Composable Commerce OAuth 2.0 for API authentication in our self-paced Authorization flows and API Clients module.

Representations

APIClient

APIClientDraft

ApiClientPagedQueryResponse

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` DateTime	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: `172800`Minimum: `3 600`Maximum: `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: `17280000`Minimum: `30`Maximum: `31 536 000`
`createdAt` DateTime	Date and time (UTC) the APIClient was initially created.

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: `172800`Minimum: `3 600`Maximum: `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: `17280000`Minimum: `30`Maximum: `31 536 000`

ApiClientPagedQueryResponse

PagedQueryResult with results containing an array of APIClient.

`limit` Int	Number of results requested. Default: `20`Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0`Maximum: `10 000`
`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` QueryPredicate	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 requested. Default: `20`
`offset` Int	Number of elements skipped. Default: `0`
`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. Default: `true`
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

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

QueryPredicate

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

Scopes cannot be changed after an API Client is created.

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