# Hosts and authorization

**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](/commerce-integration-layer/hosts-and-authorization.md#session-tokens).

```http title="GraphQL endpoint"
https://graphql.integration-layer.{region}.commercetools.com/{projectKey}/main/graphql
```

### Shopper Identity

Mint and manage shopper sessions with the [identity endpoint](/commerce-integration-layer/hosts-and-authorization.md#identity-endpoints). Minting an anonymous session requires no token.

```http title="Identity endpoint"
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](/commerce-integration-layer/hosts-and-authorization.md#commercetools-access-tokens) with `manage_commerce_integration_layer` for writes or `view_commerce_integration_layer` for reads.

```http title="Extensions endpoint"
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](/commerce-integration-layer/hosts-and-authorization.md#identity-endpoints) 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 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](/commerce-integration-layer/hosts-and-authorization.md#sessionresponse) 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.

```mermaid title="Session lifecycle for a browser storefront"
sequenceDiagram
	autonumber
	participant B as Shopper's browser
	participant P as Your server<br/>(proxy)
	participant ID as Shopper Identity
	participant GQL as Experience API<br/>(router)
	participant CT as commercetools<br/>platform

	B->>P: First page load
	P->>ID: POST /session { grant_type: anonymous,<br/>locale, currency, country }
	ID->>CT: Obtain shopper-scoped token
	ID-->>P: Session JWT (commercetools token sealed inside)
	P-->>B: Page + Set-Cookie (HttpOnly session cookie)

	B->>P: Browse (GraphQL query, cookie attached)
	P->>GQL: POST /graphql · Authorization: Bearer session token
	GQL->>CT: Validate sealed token, resolve data
	GQL-->>P: Response
	P-->>B: Response

	B->>P: Sign in (email + password)
	P->>ID: POST /session { grant_type: password }<br/>with existing session as bearer
	ID->>CT: Authenticate, merge anonymous Cart
	ID-->>P: Upgraded session JWT (same session, now a Customer)
	P-->>B: Set-Cookie (updated session cookie)

	Note over P,ID: Before expiry: POST /session { grant_type: refresh }<br/>renews the sealed commercetools token,<br/>the shopper is not asked to sign in again

	B->>P: Sign out
	P->>ID: DELETE /session
	ID->>CT: Revoke the sealed token
	ID-->>P: Session revoked (takes effect immediately)
	P-->>B: Cookie cleared
```

#### 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](/api/authorization.md).

Depending on the operation, the Commerce Integration Layer requires a token with one of the following [scopes](/api/scopes.md#commerce-integration-layer):

- `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](/commerce-integration-layer/development/get-started.md#install-the-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

[endpoint definition](/search.md?urn=ctp:cil:endpoint:/{projectKey}/main/session:POST).

### Update session presentment

[endpoint definition](/search.md?urn=ctp:cil:endpoint:/{projectKey}/main/session:PATCH).

### Sign out

[endpoint definition](/search.md?urn=ctp:cil:endpoint:/{projectKey}/main/session:DELETE).

### Select a Business Unit

[endpoint definition](/search.md?urn=ctp:cil:endpoint:/{projectKey}/main/session/business-unit:PUT).

### Select Store and Channels

[endpoint definition](/search.md?urn=ctp:cil:endpoint:/{projectKey}/main/session/scope:PUT).

### Select a distribution Channel

[endpoint definition](/search.md?urn=ctp:cil:endpoint:/{projectKey}/main/session/distribution-channel:PUT).

## Representations

### SessionResponse

[type definition](/search.md?urn=ctp:cil:type:SessionResponse).

### Request types

#### SessionRequest

[type definition](/search.md?urn=ctp:cil:type:SessionRequest).

#### AnonymousSessionRequest

[type definition](/search.md?urn=ctp:cil:type:AnonymousSessionRequest).

#### PasswordSessionRequest

[type definition](/search.md?urn=ctp:cil:type:PasswordSessionRequest).

#### RegisterSessionRequest

[type definition](/search.md?urn=ctp:cil:type:RegisterSessionRequest).

#### RefreshSessionRequest

[type definition](/search.md?urn=ctp:cil:type:RefreshSessionRequest).

#### IdpSessionRequest

[type definition](/search.md?urn=ctp:cil:type:IdpSessionRequest).

#### SessionUpdateRequest

[type definition](/search.md?urn=ctp:cil:type:SessionUpdateRequest).

#### SessionBusinessUnitRequest

[type definition](/search.md?urn=ctp:cil:type:SessionBusinessUnitRequest).

#### SessionScopeRequest

[type definition](/search.md?urn=ctp:cil:type:SessionScopeRequest).

#### SessionDistributionChannelRequest

[type definition](/search.md?urn=ctp:cil:type:SessionDistributionChannelRequest).

#### SessionGrantType

[type definition](/search.md?urn=ctp:cil:type:SessionGrantType).

#### RegisterInput

[type definition](/search.md?urn=ctp:cil:type:RegisterInput).

#### Presentment

[type definition](/search.md?urn=ctp:cil:type:Presentment).

### Errors

Identity endpoints return errors as `{ "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. |

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.

## Related pages

- [Area overview page with navigation](/commerce-integration-layer.md)
- [Previous page: API overview](/commerce-integration-layer/experience-api-overview.md)
- [Search documentation and API specs](/search.md)