XM Cloud is a purely headless CMS, so your front-end app (say, a Next.js site) calls Sitecore APIs for the layout and content rather than having on spot, similarly to what traditional monolith CMS page requests did:
At the same time, this approach brings a variety of ways that content+layout could be consumed, depending on which particular endpoint is being used and the mode it serves. I wrote this post to explain the options and differences between them.
GraphQL Endpoint Working on a Local CM in Docker containers
When you run your app locally with Docker containers, all content calls go straight to your local CM instance. For example, a Next.js app using JSS or Cloud SDK might fetch layout or GraphQL data from the local CM at endpoints like:
In other words, your locally running headless app pulls content directly from the local Sitecore CM, including any unpublished edits. You’ll usually develop this way to see live changes immediately. Notably to say, there is no mock/substitute of Experience Edge with local Docker containers, which means you only have a preview endpoint with local container-based development.
Cloud Delivery API
The Delivery API for each of the cloud environments has two modes: Preview, which runs on the CM itself, and Live from Experience Edge. Once content is published from any XM Cloud environment, it lands on Experience Edge for that environment – the cloud GraphQL delivery service. In practice:
-
Preview API: Every XM Cloud environment (dev, QA, etc.) has a preview GraphQL endpoint on its CM, at */sitecore/api/graph/edge. Content fetched here includes unpublished draft changes. Editors use this to see a work-in-progress.
-
Live API: The live GraphQL endpoint is on Experience Edge service at https://edge.sitecorecloud.io/api/graphql/v1. This serves only published content – essentially a read-only high-performance delivery API.
In other words, no publish = no live content. If you never publish your edits, the live API returns nothing (or only older content, if pre-exists), because Edge only knows what’s been pushed from the related CM.
Key differences:
When your headless app connects to a Preview endpoint (/sitecore/api/graph/edge) on your local Docker CM or cloud CM for Dev/QA/Prod, it must send an API Key for authentication. API Key is effectively an ID of an item located under /sitecore/system/Settings/Services/API Keys folder
When your headless app connects to the Live Delivery API (/api/graphql/v1) on Experience Edge, it must instead authenticate with an Experience Edge Token. Edge tokens are environment-specific. Without a proper Edge Token for a given particular environment, the /api/graphql/v1 endpoint will reject requests.
This table illustrates what
| Scenario |
Endpoint |
Auth Type |
Header |
| Local CM |
/sitecore/api/graph/edge |
API Key ID |
sc_apikey: <api-key-id> |
| Cloud CM (Dev/QA/Prod) |
/sitecore/api/graph/edge |
API Key ID |
sc_apikey: <api-key-id> |
| Experience Edge (Live) |
/api/graphql/v1 |
Experience Edge Token |
Authorization: Bearer <edge-token> |
One of the easiest ways to reach out to specific environmental access keys is through the Deploy App:
Setting up multiple preview environments
If you want multiple preview environments for dev, QA and prod, you’ll need separate deployments of your front-end. Essentially, each environment needs two “versions” of your headless app: one pointing at the CM in preview mode and one pointing to the content published to Edge (live mode). For example, in a project with 3 environments (Prod, QA, Dev), this could mean:
That’s up to 6 different sites running your headless app: 3 envs × 2 modes. Each one has different environment variables/URLs. It sounds like a lot, but it's pretty easy and quick to configure and lets each team see exactly what they need.
Hope this post explains how different modes and environments operate well together.