Authorization methods and principles used to access the commercetools Composable Commerce HTTP APIs.
Getting started
To authorize your application, do the following:
-
Determine the appropriate scopes that the client will use.
-
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.
-
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.
Request an access token using the Composable Commerce OAuth 2.0 service
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.
Best practices
To help keep the API Client secrets secure in your environments, follow these best practices:
- Rotate API Clients periodically. Create new API Clients regularly and change them immediately if you detect suspicious activities. Then, update your applications to use the new API Clients and delete the old ones. This practice helps minimize potential risks if a client is ever compromised and strengthens the protection of sensitive data by preventing attackers from re-using a compromised client.
- Limit API scopes and permissions. Follow the least privilege and need-to-know principles by restricting permissions to the minimum necessary for each application and using different API clients. This reduces the impact of a compromised API Client and the risk of unauthorized access.
- Use secure storage. Store API Client credentials securely using encryption and access controls. Avoid hardcoding credentials directly into your application code.
- Centralize management. Use a centralized system to manage and control API Clients. This facilitates tracking, monitoring, and revoking access when necessary.
- Implement monitoring and logging. As part of your own logging and monitoring processes, regularly monitor the API Client activity in the environments of your applications to identify and address suspicious or unauthorized behavior.
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:
Region | Authorization URL |
---|---|
North America (Google Cloud, Iowa) | https://auth.us-central1.gcp.commercetools.com/ |
North America (AWS, Ohio) | https://auth.us-east-2.aws.commercetools.com/ |
Europe (Google Cloud, Belgium) | https://auth.europe-west1.gcp.commercetools.com/ |
Europe (AWS, Frankfurt) | https://auth.eu-central-1.aws.commercetools.com/ |
Australia (Google Cloud, Sydney) | https://auth.australia-southeast1.gcp.commercetools.com/ |
The following hostnames are deprecated, but remain accessible as aliases:
auth.sphere.io
(Google Cloud, Belgium)auth.commercetools.co
(Google Cloud, Iowa)
If your Project uses either of these hostnames, we recommend that you update your configuration to the current hostnames.
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.
Client credentials flow
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"
}
application/x-www-form-urlencoded
media type. The scope parameter is optional, but recommended.Password flow
email
and unencrypted password
of the Customer in addition to your OAuth client credentials.email
and password
again.Password flow for global Customers
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}
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.
create_anonymous_token
scope. The regular client credentials flow is used.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
.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
/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
.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
}
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.Request an access token using an external OAuth server
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.
Using external OAuth tokens affects performance. If the token introspection fails, the API call fails. If the introspection takes 200 ms to return a result, then the API call also takes 200 ms longer to complete.
Headers
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
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
/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
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.
500 ms
. A good target is to respond within less than 50 ms.Error cases
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:
Examples
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}"
}
/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}"
}
Use an access token
access_token
.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}
...
expires_in
field.Manage 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:
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.
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.10 million
. If the limit is exceeded, the least recently used refresh tokens are deleted. Creating new refresh tokens continues to work.Revoke tokens
/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.refresh_token
or access_token
. Parameters are provided using the application/x-www-form-urlencoded
media type.This endpoint will revoke an existing token, even if the type hint is incorrect. For example, if you provide an access token, and the type hint suggests that it is a refresh token, the endpoint will still revoke it. Providing an accurate token hint will result in a faster response time. However, if you are unsure about the token type, it is more efficient to not provide the hint at all.
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.