HTTP API authorization

Getting started

To authorize your application, do the following:

1. Determine the appropriate scopes that the client will use.

2. Create an API Client in the Merchant Center or through the API Clients API.

   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.

3. Request an access token through the Composable Commerce OAuth 2.0 service or an external OAuth server.

   If you received a refresh token, you can use the refresh token flow to request future tokens.

We recommend that you use the Composable Commerce OAuth 2.0 authorization flows instead of an external OAuth server, unless your business needs require it.

Request an access token using the Composable Commerce OAuth 2.0 service

To request an access token from the Composable Commerce OAuth 2.0 service, use the authorization URL where your project is located:

The Authorization API provides the following authorization flows:

• Client credentials: creates a token for an API Client.

• Password flow: creates a token by using a customer's login credentials. These tokens are used with Me endpoints for operations scoped to a specific user session.

• Anonymous session flow: creates a token for an anonymous session. These tokens are used with Me endpoints for operations scoped to a specific user session or guest checkout scenario. A customer using this token might at some point log in or sign up by using the password flow.

• Refresh token flow: refreshes an access token.

You can also authenticate using one of the commercetools SDKs or an API tool such as Postman. We provide several Postman collections to help you connect to the Composable Commerce APIs.

Client credentials flow

To obtain an access token through the client credentials flow, issue the following request to the auth service by providing your client_id and client_secret via HTTP Basic Authentication. Here, the username is the client_id and the password is the client_secret:

POST https://{auth_host}/oauth/token
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope={scope}

Example request

$curl https://{auth_host}/oauth/token -X POST \
    --basic --user "{clientId}:{clientSecret}" \
    -d "grant_type=client_credentials&scope=manage_project:{projectKey}"

Example response

{
  "access_token": "vkFuQ6oTwj8_Ye4eiRSsqMeqLYNeQRJi",
  "expires_in": 172800, // seconds (2 days)
  "scope": "manage_project:{projectKey}",
  "token_type": "Bearer"
}

Parameters are provided using the application/x-www-form-urlencoded media type. The scope parameter is optional, but recommended.

Password flow

To obtain an access token through the password flow, provide the email and unencrypted password of the Customer in addition to your OAuth client credentials.

The response contains the access token and refresh token. If an access token expires, you can use the refresh token to obtain a new access token without supplying the Customer's email and password again.

Password flow for global Customers

Use this flow when your Customer is not associated with any Stores. To obtain an access token for a Customer in a specific Store, see Password flow for Customers in a Store.

POST https://{auth_host}/oauth/{projectKey}/customers/token
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded

grant_type=password&username={email}&password={password}&scope={scope}

Example request

$curl https://{auth_host}/oauth/{projectKey}/customers/token -X POST \
    --basic --user "{clientId}:{clientSecret}" \
    -d "grant_type=password&username=alice@example.com&password=secret&scope=view_published_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey}"

Example response

{
  "access_token": "v-dZ10ZCpvbGfwcFniXqfkAj0vq1yZVI",
  "expires_in": 172800, // seconds (2 days)
  "scope": "view_published_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey} customer:{id}",
  "refresh_token": "{projectKey}:OWStLG0eaeVs7Yx3-mHcn8iAZohBohCiJSDdK1UCJ9U",
  "token_type": "Bearer"
}

Password flow for Customers in a Store

Use this flow when a Customer belongs to one or more Stores. The access token is valid only for the Store specified in the request.

POST https://{auth_host}/oauth/{projectKey}/in-store/key={storeKey}/customers/token
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded

grant_type=password&username={email}&password={password}&scope={scope}

Refresh token flow

The refresh token flow is used when the access token obtained through the password flow expires. It lets you continue the user’s session or provide ongoing access without asking the user to log in again, thereby maintaining a seamless user experience.

To obtain an access token through the refresh token flow, provide the OAuth client credentials and the refresh token.

POST https://{auth_host}/oauth/token
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token={token}

By default, refresh tokens expire 200 days after last usage or if the limit of 10 million refresh tokens is exceeded (in the latter case, the least recently used tokens expire first). Therefore a refresh token that is frequently used will never expire.

Tokens for anonymous sessions

Anonymous sessions give users access to resources or services that do not require personal identification. This is useful in scenarios where you need to offer certain functionality to your customers without requiring them to log in or create an account.

To obtain an access token for an anonymous session, the OAuth client needs the create_anonymous_token scope. The regular client credentials flow is used.

These access tokens are similar to those issued with the password flow, but instead of being linked to a specific customer, they are associated with an anonymousId. In addition to the access token, a refresh token is issued. The refresh token is the only way to get a new access token for the associated anonymousId.

The anonymousId is either generated by the API or an unused ID can be supplied by adding the anonymous_id={id} parameter.

POST https://{auth_host}/oauth/{projectKey}/anonymous/token
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope={scope}

Example request

$curl https://{auth_host}/oauth/{projectKey}/anonymous/token -X POST \
    --basic --user "{clientId}:{clientSecret}" \
    -d "grant_type=client_credentials&scope=view_published_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey}&anonymous_id={uniqueId}"

Example response

{
  "access_token": "v-dZ10ZCpvbGfwcFniXqfkAj0vq1yZVI",
  "expires_in": 172800, // seconds (2 days)
  "scope": "view_published_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey} anonymous_id={uniqueId}",
  "refresh_token": "{projectKey}:OWStLG0eaeVs7Yx3-mHcn8iAZohBohCiJSDdK1UCJ9U",
  "token_type": "Bearer"
}

Introspection

The authorization service also implements OAuth 2.0 Token Introspection available under /oauth/introspect. This feature lets you verify the active state of an OAuth 2.0 access token and retrieve meta-information such as the scope.

Like the other endpoints, it is protected by client authentication. A client can always introspect its own access tokens. A client with introspect_oauth_tokens:{projectKey} permission (also implied by manage_project) can introspect any access token in that project, even if it was issued to a different client. If the requesting client does not have the permission to introspect the given token, it is treated as not active and no further information is returned.

Example request

$curl https://{auth_host}/oauth/introspect -X POST \
        --basic --user "{clientId}:{clientSecret}" \
        -d "token=nbzLp_xTvAmPJnilFuZGaiukILpuaCxQ"

Example response (active)

{
  "active": true,
  "scope": "view_products:example-project-26",
  "exp": 1501158800852, // Unix epoch (Thu Jul 27 2017 12:33:20 GMT+0000)
  "client_id": "tl-zzoobQGyBbFhqccWB_ZiK"
}

Example response (inactive)

{
  "active": false
}

If active is true, the access token can currently be used with the API, within the scope. The exp timestamp indicates when this token will expire.

You may cache the result, but consider that a token can not only expire, but also be revoked earlier (for example if the client that issued the token is deleted). The RFC 7662, Section 4 summarizes the tradeoff in the second-last paragraph.

Request an access token using an external OAuth server

To use OAuth 2.0 Bearer tokens issued by another service, provide an RFC 7662-compliant OAuth 2.0 Token Introspection endpoint to your Project using the Set ExternalOAuth update action.

The Composable Commerce Authorization API calls the provided endpoint to verify the validity of the token and check the token's scopes. The API only accepts its own scopes. Any scopes that are not listed in the Scopes section are ignored.

Some services, especially OpenID Connect implementations, might already provide such an endpoint and might allow embedding permissions specific to Composable Commerce into the scope. In other cases, you might need to implement a service specifically to verify the token or create the scope.

A Project that uses tokens issued by an external OAuth service can continue to use tokens issued by Composable Commerce. The APIs validate the tokens against the respective introspection endpoints with no additional configuration required. The API might cache External OAuth tokens for up to 30 minutes to improve response times.

Headers

When calling the introspection endpoint of an external OAuth server, in addition to the Authorization header, the request will also contain a correlation ID if there is one available:

• X-Correlation-ID - A correlation ID can be used to track a request. The same correlation ID will be returned to the original caller of the API.

Secure the OAuth introspection endpoint

As specified in RFC 7662, the OAuth introspection endpoint must not be publicly accessible. You need to configure the Authorization Header that you want the API to use. For example, you can use HTTP Basic Authentication by saving a header like Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==. You can also use OAuth 2.0 Bearer tokens, and refresh the used token on a regular basis by updating the Project configuration.

Handle permissions for customer accounts or anonymous sessions

If you want to use external OAuth tokens with the /me endpoints, you'll have to add an already existing customer account, or an anonymous session, into the scope. For a customer account, add customer_id:{id}, for an anonymous session, add anonymous_id:{id} to the scope.

The synchronization of customer accounts between the external service and Composable Commerce should, for performance reasons, not be done during the token verification. Ideally, the customer accounts are created before a token for the customer is issued to be used with the Composable Commerce APIs.

Limits and error cases

The External OAuth token introspection affects the performance and uptime of commercetools Composable Commerce. Therefore, you should carefully consider the technology used to implement the introspection and your hosting options. Regardless of the technology choice, ensure that the network latency between the Region where your Project is located and your introspection endpoint is as low as possible.

Time limits

If the introspection does not respond fast enough, then the whole API call is blocked. As a result, we enforce the following limits:

• The introspection endpoint must return a result within 500 ms to the Authorization API. This includes the network latency between the two.

We recommend that your introspection endpoint returns results much faster than 500 ms. A good target is to respond within less than 50 ms.

Error cases

In any error case (no response within the time limit or a bad response like a 500 HTTP status code) the API call fails. The introspection is not retried within an API call. Further API calls will try to reach the introspection endpoint again.

The following errors codes are returned when the introspection endpoint does not respond successfully:

• 502 or 504 ExternalOAuthFailed

Examples

Assuming you have configured the URL https://example.org/oauth/introspect and the Authorization Header Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==, and you make a request to /{projectKey}/products, your endpoint will receive the following request:

POST /oauth/introspect
Host: example.org
Content-Type: application/x-www-form-urlencoded
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

token={token}

If your endpoint responds with the following, the API request will succeed:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "active": true,
  "scope": "view_published_products:{projectKey}"
}

If your endpoint responds with one of the following, the API request will not succeed, either because the token is invalid, or because the client does not have the permission to view products:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "active": false
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "active": true,
  "scope": "view_orders:{projectKey}"
}

The following example shows a response for a token that can be used with the /me endpoints:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "active": true,
  "scope": "view_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey} customer_id:{id}"
}

Using an access token

Upon successful completion of an authorization flow, the OAuth 2.0 service returns an access_token.

Use the access token in the Authorization header of all requests to commercetools Composable Commerce as follows:

POST /{{projectKey}}/channels HTTP/1.1
Host: api.{region}.commercetools.com
Authorization: Bearer {accesstoken}

...

commercetools Composable Commerce does not support sending access tokens as URI parameters, as defined in RFC 6750 section 2.3.

The remaining lifetime of an access token is indicated by its expires_in field.

Managing token requests

For security reasons, we advise requesting tokens sparingly and keeping the number of active tokens to a minimum whenever possible.

We do not recommend requesting a token for every work item. If a client application requests too many tokens, it might be rate-limited.

We recommend getting new tokens when appropriate using automatic token management. Our SDK clients provide support for automatic token management, or you can implement token management yourself.

Short-lived applications

In some scenarios, your SDK clients are short-lived. For example, a script triggered by a cron job which creates a client every time the job runs, or a function in a serverless Function-as-a-Service environment.

We recommend the following approaches when working with short-lived client applications to reduce the number of requested tokens.

One approach is to store a token either in the filesystem, a cache, or the application's configuration. You can then refresh the token at a regular interval. In this approach, all instances of your application use the same token.

You can pass an existing token to the client by using the following SDKs:

• JVM SDK
• NodeJS SDK
• PHP

In a serverless FaaS environment, you should be able to use the global execution context to store your client across warm invocations (when the FaaS re-uses a function instance and it is not subject to a cold-start). Here is an example for an AWS Lambda function that uses the execution context.

Create anonymous sessions only once necessary

At first sight, creating a new token with a new anonymous session on the first request is the most straight forward implementation. However, this pattern results in a very high number of unused anonymous sessions, for example if a stateless web crawler acts like a new visitor on every request or if visitors drop off after only browsing the site.

To avoid creating unused anonymous sessions, hold a visitor-independent client credentials flow token (for example with only the view_published_products scope) and only request a token with an anonymous session when the visitor creates a cart, shopping list or other visitor-specific resource. A single API Client can be used to create both types of tokens.

Note that the number of refresh tokens is limited to 10 million. If the limit is exceeded, the least recently used refresh tokens are deleted. Creating new refresh tokens continues to work.

Revoking tokens

The Composable Commerce authorization service implements Auth 2.0 Token Revocation under /oauth/token/revoke. This endpoint provides a mechanism to invalidate access and refresh tokens within the authorization server. For example, when a customer logs out, changes identity, or uninstalls your application, you might want to revoke the tokens associated with the customer. This behavior prevents the abuse of abandoned tokens and can contribute to a better customer experience.

Only tokens that were issued to the client making the revocation request are allowed to be revoked by the client. To revoke a token, it is necessary to provide the token, and optionally a type hint. The type hint can either be refresh_token or access_token. Parameters are provided using the application/x-www-form-urlencoded media type.

Example request

$curl https://{auth_host}/oauth/token/revoke -X POST \
    --basic --user "{clientId}:{clientSecret}" \
    -d "token={token}&token_type_hint={access_token|refresh_token}"

Response

The endpoint will only provide a status code for the response:

• 200 - the token was found and revoked, or the token request was invalid.
• 5xx - in case of a server error, the client has to assume that the token still exists, and should retry after a reasonable delay.