Endpoints and authorization flows for the Commerce Integration Layer.

Hosts

The Commerce Integration Layer exposes three public hosts per Project, each keyed by your Project's key. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled.

Experience

Query the Experience API with a session token.
GraphQL endpointhttp
https://graphql.integration-layer.{region}.commercetools.com/{projectKey}/main/graphql

Shopper Identity

Mint and manage shopper sessions with the identity endpoint. Minting an anonymous session requires no token.
Identity endpointhttp
https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session

Extensions

Manage extensions and schemas in your Project (publish, config, GET /schema/api, and others). Requires a commercetools access token with manage_commerce_integration_layer for writes or view_commerce_integration_layer for reads.
Extensions endpointhttp
https://extensions.integration-layer.{region}.commercetools.com/{projectKey}/main/…

Authorization

The Commerce Integration Layer uses two kinds of credentials, one for shoppers and one for tooling and automation.

Session tokens

Session tokens authorize shopper requests to the Experience API. A session token is minted from the identity endpoint and represents an anonymous or signed-in shopper.

Storefront code only handles the session token; the Commerce Integration Layer manages commercetools credentials.

What's inside the session token

The session token is an opaque signed JWT. Do not decode it or rely on its structure.

The session token includes the following conceptual information:

Inside the tokenNotes
The Project it belongs toChecked against the Project in the URL on every request
Who the shopper isAn anonymous visitor, or a signed-in Customer
Presentment contextLocale, currency, and country
Scope selectionThe selected Business Unit, Store, and distribution and supply Channels, when set. A Store can be selected without a Business Unit
A sealed commercetools tokenEncrypted. Only the Commerce Integration Layer can read it

Retrieve session information via the API:

  • The session response returns identity and expires_in whenever you mint, sign in, or reissue.
  • Shopper identity and profile come from the Experience API (me); the B2B selection comes from activeBusinessUnit.

Session lifecycle

The following sequence illustrates the session lifecycle for a browser storefront. A same-domain proxy fronts the Experience API and Shopper Identity.

Sessions across touchpoints

Session tokens are standard bearer credentials, independent of browsers, devices, or cookies.

  • Web stores it in an HttpOnly cookie behind a proxy on your domain.
  • Native apps and server-side clients store it in secure storage and call the Commerce Integration Layer hosts directly. No proxy needed.

Each touchpoint must mint its own session. Sharing tokens between touchpoints is not supported.

Shopper identity provides continuity across touchpoints. The active Cart is never stored in the session: it is resolved from the commercetools platform on every request. A Customer signed in on both web and mobile sees the same Cart, orders, and account on both, even though each device holds its own session.

commercetools access tokens

commercetools access tokens authorize tooling and automation, such as publishing extensions and setting extension configuration. These are standard tokens from the HTTP API authorization flows.
Depending on the operation, the Commerce Integration Layer requires a token with one of the following scopes:
  • manage_commerce_integration_layer:{projectKey} or manage_project:{projectKey} for a client that manages extension configuration.
  • view_commerce_integration_layer:{projectKey} for a client that only reads extension configuration.
The commercetools CLI obtains and reuses a token for you when you run commercetools auth login.

Identity endpoints

Sessions are managed through REST endpoints on the identity host, relative to /{projectKey}/main. GraphQL never mints or rotates a session.

Create or upgrade a session

POST
https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session
Mints or upgrades a shopper session. The grant is defined by grant_type in the request body and defaults to anonymous.
Minting an anonymous session requires no token. For other grants, send the session token as bearer where required, for example for refresh, or for password to merge an anonymous Cart.
Path parameters:
projectKey
​
String
​
Key of the Project.
region
​
String
​

Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled.

Request Body:SessionRequestasapplication/json
Response:
200

SessionResponse

as
application/json
Request Example:cURL
curl https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session -i \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "grant_type" : "anonymous",
  "locale" : "en-US",
  "currency" : "USD",
  "country" : "US"
}
DATA
200 Response Example: SessionResponsejson
{
  "token": "<session token>",
  "expires_in": 172800,
  "identity": "anonymous"
}

Update session presentment

PATCH
https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session

Updates the presentment (locale, currency, country) of the session and reissues the token.

OAuth 2.0 Scopes:
Path parameters:
projectKey
​
String
​
Key of the Project.
region
​
String
​

Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled.

Request Body:SessionUpdateRequestasapplication/json
Response:
200

SessionResponse

as
application/json
Request Example:cURL
curl -X PATCH https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "locale" : "de-DE",
  "currency" : "EUR",
  "country" : "DE"
}
DATA

Sign out

DELETE
https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session

Signs out the shopper and revokes the session, including the previous token from a refresh that has not expired yet. The revocation takes effect immediately.

OAuth 2.0 Scopes:
Path parameters:
projectKey
​
String
​
Key of the Project.
region
​
String
​

Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled.

Response:
204
Request Example:cURL
curl -X DELETE https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Select a Business Unit

PUT
https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session/business-unit

Selects a B2B Business Unit and Store for the session and reissues the token. Requires a signed-in Customer session that is an associate of the Business Unit.

OAuth 2.0 Scopes:
Path parameters:
projectKey
​
String
​
Key of the Project.
region
​
String
​

Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled.

Request Body:SessionBusinessUnitRequestasapplication/json
Response:
200

SessionResponse

as
application/json

Select Store and Channels

PUT
https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session/scope

Selects the Store and the supply and distribution Channels of the session, and reissues the token. Works for every session, including an anonymous one. A session scoped to a Business Unit stays within the Stores of that Business Unit.

OAuth 2.0 Scopes:
Path parameters:
projectKey
​
String
​
Key of the Project.
region
​
String
​

Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled.

Request Body:SessionScopeRequestasapplication/json
Response:
200

SessionResponse

as
application/json
Request Example:cURL
curl -X PUT https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session/scope -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "storeKey" : "berlin",
  "distributionChannelId" : null
}
DATA

Select a distribution Channel

PUT
https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session/distribution-channel
Selects the distribution Channel that scopes Channel-specific prices for the session and reissues the token. Pass distributionChannelId: null to clear an explicit selection.
OAuth 2.0 Scopes:
Path parameters:
projectKey
​
String
​
Key of the Project.
region
​
String
​

Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled.

Request Body:SessionDistributionChannelRequestasapplication/json
Response:
200

SessionResponse

as
application/json
Request Example:cURL
curl -X PUT https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session/distribution-channel -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "distributionChannelId" : null
}
DATA

Representations

SessionResponse

Session token to send as the bearer credential for the Experience API (GraphQL). The commercetools token sealed inside the session token never leaves the Commerce Integration Layer.

token​
String​

Opaque signed JWT. Do not decode it or rely on its structure.

expires_in​
Int​

Lifetime of the token in seconds. It depends on how the session was minted, so don't hard-code a value:

  • A session from the anonymous, password, or register grant expires with its sealed commercetools access token, by default 48 hours after it was minted or last refreshed. Updating presentment or selecting a scope reissues the token without extending this.
  • A session from the idp grant lasts up to 30 days after it was minted or last refreshed.
identity​
String​
Identity of the shopper, for example anonymous.

Request types

SessionRequest

Request body for POST /session. The grant_type determines the other fields that apply.
locale​
String​

Locale of the session.

currency​
String​

Currency of the session.

country​
String​

Country of the session.

grant_type​
Grant to use. Defaults to anonymous when omitted.

AnonymousSessionRequest

Mints an anonymous shopper session. Requires no bearer token.

locale​
String​

Locale of the session.

currency​
String​

Currency of the session.

country​
String​

Country of the session.

grant_type​
anonymous
Grant to use. Defaults to anonymous when omitted.

PasswordSessionRequest

Mints a signed-in Customer session. Merges an anonymous Cart when a prior session bearer is sent.

locale​
String​

Locale of the session.

currency​
String​

Currency of the session.

country​
String​

Country of the session.

grant_type​
password
Grant to use. Defaults to anonymous when omitted.
email​
String​

Email address of the Customer.

password​
String​

Password of the Customer.

RegisterSessionRequest

Creates a Customer, then mints a signed-in session.

locale​
String​

Locale of the session.

currency​
String​

Currency of the session.

country​
String​

Country of the session.

grant_type​
register
Grant to use. Defaults to anonymous when omitted.
input​

RefreshSessionRequest

Refreshes the sealed commercetools token behind an existing session. Requires a valid session token as bearer. Refresh a few minutes before expiry. The previous token keeps working until it expires, so in-flight requests don't fail. After the session token expires, this grant returns 401 and you must mint a new session; a signed-in shopper must sign in again.
locale​
String​

Locale of the session.

currency​
String​

Currency of the session.

country​
String​

Country of the session.

grant_type​
refresh
Grant to use. Defaults to anonymous when omitted.

IdpSessionRequest

Signs in through an external OIDC identity provider. Provide either code or id_token.
locale​
String​

Locale of the session.

currency​
String​

Currency of the session.

country​
String​

Country of the session.

grant_type​
idp
Grant to use. Defaults to anonymous when omitted.
code​
String​

Authorization code issued by the identity provider.

id_token​
String​

ID token issued by the identity provider.

SessionUpdateRequest

Request body for PATCH /session. Provide the presentment values to change.
locale​
String​

Locale of the session.

currency​
String​

Currency of the session.

country​
String​

Country of the session.

SessionBusinessUnitRequest

Selects the B2B Business Unit and Store of a session.

businessUnitKey​
String​

Key of the Business Unit to select.

storeKey​
String​

Key of the Store to select. It must be one of the Stores of the Business Unit.

SessionScopeRequest

Selects the Store and Channels of a session. Provide at least one property. A property that is omitted is left unchanged, and null clears it.
storeKey​
Can be String or Nil​
Key of the Store to select. Pass null to leave Store scope, which also clears both Channels unless the same request names them. A session scoped to a Business Unit cannot clear its Store.
supplyChannelId​
Can be String or Nil​
Identifier of the inventory supply Channel to select. The Channel must have the InventorySupply role. Pass null to clear the selection.
distributionChannelId​
Can be String or Nil​
Identifier of the distribution Channel to select. The Channel must have the ProductDistribution role. Pass null to clear the selection.

SessionDistributionChannelRequest

Selects the distribution Channel that scopes Channel-specific prices for the session.

distributionChannelId​
Can be String or Nil​
Identifier of the distribution Channel to select. Pass null to clear an explicit selection.

SessionGrantType

Grant used to mint or upgrade a session.

anonymous

An anonymous shopper session.

password

A signed-in customer session. Merges an anonymous cart when a prior session bearer is sent.

register

Creates a customer, then mints a signed-in session.

refresh

Refreshes the sealed commercetools token behind an existing session. Requires a valid session token as bearer.

idp
Signs in through an external OIDC identity provider.
extension
Signs in through your Project's own extension, which authenticates the shopper and tells the Commerce Integration Layer who they are. Requires the extension to export onResolveLogin on its hooks object; refused otherwise.

RegisterInput

Customer data for the register grant.
email​
String​
password​
String​
firstName​
String​
lastName​
String​
companyName​
String​

Presentment

Presentment context of a session. If omitted, values fall back to the existing session, and then to the Project's configured defaults. A GraphQL query with no resolvable presentment fails with SESSION_MISSING_PRESENTMENT.
locale​
String​

Locale of the session.

currency​
String​

Currency of the session.

country​
String​

Country of the session.

Errors

Identity endpoints return errors as { "error": "<code>", "error_description": "<text>" }. Common codes:
StatuserrorMeaning
400invalid_requestA required body field is missing.
400unsupported_grant_typeThe grant_type is not one of the supported grants.
400registration_failedRegistration failed. The response deliberately doesn't reveal whether the email is already registered.
400unsupported_presentmentThe locale, currency, or country is outside the Project's configured values. The response names the allowed values.
401invalid_credentialsThe email or password is wrong.
401invalid_tokenThe bearer is missing, expired, or revoked.
403project_mismatchThe bearer was minted for a different Project.
403store_not_in_business_unitThe Store is not one of the selected Business Unit's Stores.
403unsupported_by_storeA Store-scoped session can't use the requested presentment value.
A GraphQL request with no bearer, an invalid bearer, or a revoked session gets HTTP 401, and a bearer from a different Project gets 403. On 401, mint a new anonymous session.