Authentication and authorization

API Clients

To access the Composable Commerce APIs you need to create an API Client inside your Project. Each Project can have multiple API Clients, each used for a specific application.

API Clients grant tokens from https://auth.{region}.commercetools.com, which are then used to access resources on https://api.{region}.commercetools.com.

An API Client consists of the following:

The first API Client in a Project must be created using the Merchant Center. After that, you can use either the Merchant Center or the Authorization API to create additional API Clients, depending on your specific requirements.

The Create API Client endpoint on the Authorization API is helpful in these common scenarios:

• When you use an infrastructure as code service (such as Terraform) or a configuration management solution.
• When you need to define when the API Client's access expires.

Temporary access

API Clients remain valid until they are deleted in the Merchant Center or through the Delete API Client endpoint, unless a deleteDaysAfterCreation value is set during creation. The system automatically deletes the API Client once the date calculated in deleteDaysAfterCreation has passed.

The validity period of the tokens generated by the API Client is determined by the values assigned to the accessTokenValiditySeconds and refreshTokenValiditySeconds properties on the API Client. If these properties are not set at the creation of the API Client, the default validity is used.

If you need to provide temporary access, for example, to a third party such as a contract developer or systems integrator, you can provide them with their own API Client. In this case, you can set a value for deleteDaysAfterCreation through the Create API Client endpoint. This ensures that access is automatically revoked at the end of the contract period. In addition, you can track changes made by the API Client with Audit Log Premium.

Application-specific usage

We recommend that you create an API Client for each application that you have.

Let's imagine that your Project contains the following application integrations:

• A commerce website using a composable frontend.
• A product information management (PIM) system integration using an off-the-shelf connector.
• A custom-built integration to sync new Orders to the enterprise resource planning (ERP) system.

In this case, you should create three API Clients, each with its own distinct scopes that are limited to only what is absolutely necessary for that application. In the event of a security breach that exposes the API Client or token(s) of a single application, the potential impact will be limited. This is also the reason that we advise against creating a general-purpose API Client with permissive scopes.

Grant types and usage

Grant types are the methods available to an application to generate an access token that grants access to the resources of your Composable Commerce Project. An API Client can use different grant types based on the configured scopes.

The following grant types are used in Composable Commerce:

• Client credentials
• Password and anonymous (often used together)

Grant types are paired with a commerce application, and the grant flow is done client side or server side.

The following table describes how each grant type is commonly used:

Applications that do not have a middleware but require access to resources restricted to a particular Customer can use the password or anonymous flows. This allows them to acquire an access token specifically scoped to the me endpoints. Scopes designed for the me endpoints include "my" within the scope name (for example, manage_my_carts and manage_my_shopping_lists). These scopes and endpoints ensure that the Customer (or anonymous user) can only view and modify their own resources.

One exception to an application using only scopes designed for the me endpoints, is when the application also grants the view_products scope. Allowing this scope is acceptable when all Customers are permitted to view the same products.

Grant flows

Client credentials flow

The client credentials flow is used for general application usage and unlike the password and anonymous flows, is not scoped towards any individual Customer (or anonymous user).

This grant type uses a backend server to complete the grant flow. For security purposes, the token is stored on the server and is not shared with the client.

1. The frontend application makes a request to the backend server, such as a Backend for Frontend (BFF).
2. The backend server requests an access token from the authentication server using the client credentials (client_id and client_secret).
3. The authentication server validates the client credentials and sends back the access_token, token_type, expires_in, and scope.
4. The backend server uses the access_token to access the commercetools API.
5. The commercetools API returns the data to the backend server.
6. The backend server processes and returns the data to the frontend.

Validation example

Let's take a closer look at steps #2 and #3, where the authentication server validates the client credentials.

The following example is a request for an access token to the authentication server:

https://{auth_host}/oauth/token -X POST \
 --basic --user "{clientId}:{clientSecret}" \
 -d "grant_type=client_credentials&scope=manage_products:furniture_shop_au_prod
 manage_customers:furniture_shop_au_prod"

A successful request will return a response similar to this:

{
  "access_token": "RydkYXkgbWF0ZSwgYWNjZXNzIHRva2Vu",
  "token_type": "Bearer",
  "expires_in": 172800,
  "scope": "manage_products:furniture_shop_au_prod
            manage_customers:furniture_shop_au_prod
            view_products:furniture_shop_au_prod
            view_customers:furniture_shop_au_prod"
}

• access_token: the token to access resources through the commercetools API
• token_type: the type of the token
• expires_in: the number of seconds until token expiration (48 hours by default)
• scope: the list of granted scopes

Password flow

The password flow uses the Customer's username (email) and password to create an access token.

Client-side grant

1. The client-side application requests an access token from the authentication server using the user-provided credentials (username and password).
2. The authentication server validates the credentials and sends back the access_token, token_type, refresh_token, expires_in, and scope.
3. The client-side application uses the access_token to access the commercetools API.
4. The commercetools API returns the data to the client-side application.

Server-side grant

1. The client-side application sends the user-provided credentials (username and password) to the backend server.

2. The backend server requests an access token from the authentication server using the user’s credentials.

3. The authentication server validates these credentials and sends back the access_token, token_type, refresh_token, expires_in, and scope.

4. The backend server uses the access_token to access the commercetools API.

5. The commercetools API returns the data to the backend server.

6. The backend server processes the data using one of the following options:

   • Option 1: Encrypts the tokens on the backend server and sends them to the client-side application as an encrypted cookie. The client-side application then stores the cookie locally and includes it with each request to the backend server.
   • Option 2: The tokens are stored in a cache on the backend server and a reference to the cache is sent to the client-side application as a cookie. The client-side application then stores the cookie locally and includes it with each request to the backend server.

In this flow, the authorization happens on the backend server and ensures that the client-side application never sees the actual token values. This method reduces the risk of unauthorized access to the commercetools APIs.

Anonymous session flow

This flow creates a token for each anonymous session, which can be used, for example, in guest checkout scenarios where the user hasn't logged in.

Anonymous tokens are similar to tokens issued with the password grant flow and are intended to be used with scopes designed for the me endpoints. This token type returns a unique anonymous_id that is used to access a user's resources. If a user with an anonymous_id creates an account, this identifier can also be used to assign any existing resources to the newly created Customer.

It is standard practice to use the anonymous and password flows together in the same application but not the client credentials flow.

Common errors

When consuming client credentials, password, or anonymous flow tokens, different errors can be returned. You can define solutions to handle these errors and recover without needing human intervention.

Authentication server errors

API server errors

Common scenarios

Token expiration

All tokens have a set lifespan which you see when you:

• Create the token: the value of the expires_in field provides the number of seconds until the token expires.
• Introspect the token: the value of the exp field provides a Unix timestamp that details when the token expires.

If a client credentials token expires, the client must reauthenticate by requesting a new token. If a password or anonymous flow token expires, use the refresh token flow instead of requesting a new set of tokens.

Logging out a Customer

To log out a Customer, do the following:

1. Clear the user's session: if the user is not linked to the session they must re-authenticate with their credentials.
2. Revoke the token: you can revoke the anonymous or password token by using the token revocation endpoint.

Test your knowledge