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
https://graphql.integration-layer.{region}.commercetools.com/{projectKey}/main/graphql
Shopper Identity
https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session
Extensions
GET /schema/api, and others). Requires a commercetools access token with manage_commerce_integration_layer for writes or view_commerce_integration_layer for reads.https://extensions.integration-layer.{region}.commercetools.com/{projectKey}/main/…
Session tokens
Storefront code only handles the session token; the Commerce Integration Layer manages commercetools credentials.
What's inside the session token
The session token includes the following conceptual information:
| Inside the token | Notes |
|---|---|
| The Project it belongs to | Checked against the Project in the URL on every request |
| Who the shopper is | An anonymous visitor, or a signed-in Customer |
| Presentment context | Locale, currency, and country |
| Scope selection | The selected Business Unit, Store, and distribution and supply Channels, when set. A Store can be selected without a Business Unit |
| A sealed commercetools token | Encrypted. Only the Commerce Integration Layer can read it |
Retrieve session information via the API:
- The session response returns
identityandexpires_inwhenever you mint, sign in, or reissue. - Shopper identity and profile come from the Experience API (
me); the B2B selection comes fromactiveBusinessUnit.
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
manage_commerce_integration_layer:{projectKey}ormanage_project:{projectKey}for a client that manages extension configuration.view_commerce_integration_layer:{projectKey}for a client that only reads extension configuration.
commercetools auth login.Identity endpoints
/{projectKey}/main. GraphQL never mints or rotates a session.Create or upgrade a session
grant_type in the request body and defaults to anonymous.refresh, or for password to merge an anonymous Cart.projectKeyString | Key of the Project. |
regionString | Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled. |
application/jsonapplication/jsoncurl 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{
"token": "<session token>",
"expires_in": 172800,
"identity": "anonymous"
}Update session presentment
Updates the presentment (locale, currency, country) of the session and reissues the token.
projectKeyString | Key of the Project. |
regionString | Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled. |
application/jsonapplication/jsoncurl -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"
}
DATASign out
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.
projectKeyString | Key of the Project. |
regionString | Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled. |
curl -X DELETE https://auth.integration-layer.{region}.commercetools.com/{projectKey}/main/session -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"Select a 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.
projectKeyString | Key of the Project. |
regionString | Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled. |
application/jsonapplication/jsonSelect Store and Channels
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.
projectKeyString | Key of the Project. |
regionString | Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled. |
application/jsonapplication/jsoncurl -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
}
DATASelect a distribution Channel
distributionChannelId: null to clear an explicit selection.projectKeyString | Key of the Project. |
regionString | Region in which the Commerce Integration Layer is hosted. commercetools provides the exact host for your Region when the Commerce Integration Layer is enabled. |
application/jsonapplication/jsoncurl -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
}
DATARepresentations
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.
tokenString | Opaque signed JWT. Do not decode it or rely on its structure. |
expires_inInt | Lifetime of the token in seconds. It depends on how the session was minted, so don't hard-code a value:
|
identityString | Identity of the shopper, for example anonymous. |
Request types
SessionRequest
POST /session. The grant_type determines the other fields that apply.localeString | Locale of the session. |
currencyString | Currency of the session. |
countryString | Country of the session. |
grant_type | Grant to use. Defaults to anonymous when omitted. |
AnonymousSessionRequest
Mints an anonymous shopper session. Requires no bearer token.
localeString | Locale of the session. |
currencyString | Currency of the session. |
countryString | Country of the session. |
grant_type | anonymousGrant 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.
localeString | Locale of the session. |
currencyString | Currency of the session. |
countryString | Country of the session. |
grant_type | passwordGrant to use. Defaults to anonymous when omitted. |
emailString | Email address of the Customer. |
passwordString | Password of the Customer. |
RegisterSessionRequest
Creates a Customer, then mints a signed-in session.
localeString | Locale of the session. |
currencyString | Currency of the session. |
countryString | Country of the session. |
grant_type | registerGrant to use. Defaults to anonymous when omitted. |
input |
RefreshSessionRequest
401 and you must mint a new session; a signed-in shopper must sign in again.localeString | Locale of the session. |
currencyString | Currency of the session. |
countryString | Country of the session. |
grant_type | refreshGrant to use. Defaults to anonymous when omitted. |
IdpSessionRequest
code or id_token.localeString | Locale of the session. |
currencyString | Currency of the session. |
countryString | Country of the session. |
grant_type | idpGrant to use. Defaults to anonymous when omitted. |
codeString | Authorization code issued by the identity provider. |
id_tokenString | ID token issued by the identity provider. |
SessionUpdateRequest
PATCH /session. Provide the presentment values to change.localeString | Locale of the session. |
currencyString | Currency of the session. |
countryString | Country of the session. |
SessionBusinessUnitRequest
Selects the B2B Business Unit and Store of a session.
businessUnitKeyString | Key of the Business Unit to select. |
storeKeyString | Key of the Store to select. It must be one of the Stores of the Business Unit. |
SessionScopeRequest
null clears it.storeKeyCan 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. |
supplyChannelIdCan 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. |
distributionChannelIdCan 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.
distributionChannelIdCan 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.
anonymousAn anonymous shopper session.
passwordA signed-in customer session. Merges an anonymous cart when a prior session bearer is sent.
registerCreates a customer, then mints a signed-in session.
refreshRefreshes 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
onResolveLoginon itshooksobject; refused otherwise.
RegisterInput
register grant.emailString | |
passwordString | |
firstNameString | |
lastNameString | |
companyNameString |
Presentment
SESSION_MISSING_PRESENTMENT.localeString | Locale of the session. |
currencyString | Currency of the session. |
countryString | Country of the session. |
Errors
{ "error": "<code>", "error_description": "<text>" }. Common codes:| Status | error | Meaning |
|---|---|---|
400 | invalid_request | A required body field is missing. |
400 | unsupported_grant_type | The grant_type is not one of the supported grants. |
400 | registration_failed | Registration failed. The response deliberately doesn't reveal whether the email is already registered. |
400 | unsupported_presentment | The locale, currency, or country is outside the Project's configured values. The response names the allowed values. |
401 | invalid_credentials | The email or password is wrong. |
401 | invalid_token | The bearer is missing, expired, or revoked. |
403 | project_mismatch | The bearer was minted for a different Project. |
403 | store_not_in_business_unit | The Store is not one of the selected Business Unit's Stores. |
403 | unsupported_by_store | A Store-scoped session can't use the requested presentment value. |
401, and a bearer from a different Project gets 403. On 401, mint a new anonymous session.