API Gateway Authentication

The Merchant Center uses a secure JWT (JSON Web Token) Cookie named mcAccessToken to transport session information about the user. Using a Cookie allows network requests to send the session information without your application needing to explicitly handle the access token.

You can see in the project starter example that there is no need to manually handle the access token. Authentication is built into the <ApplicationShell> and managed for you.

Obtaining an access token

The mcAccessToken is granted upon user login and is stored in the secure Cookie from the Merchant Center API Gateway.

Two endpoints are available for different login strategies:

/tokens: Logins using email and password.
/tokens/sso: Logins using an idToken from an SSO workflow (see Single-Sign-On).

Each Merchant Center application uses the <ApplicationShell> React component, which provides a built-in authentication mechanism for the HTTP clients. You won't need to manually request a token from these endpoints.

Sending an authenticated request

Given that the mcAccessToken is stored in a secure cookie, HTTP clients only need to tell the browser to send the cookies with the request.

For example, to make requests to the commercetools platform HTTP API, you would prefix the request with /proxy/ctp and set credentials: "include"

// Direct request to the commercetools platform HTTP API
fetch(`https://api.europe-west1.gcp.commercetools.com/${projectKey}/orders`, {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authentication: `Bearer ${oauthToken}`,
  },
});
// Proxied request to the commercetools platform HTTP API
fetch(`https://mc-api.europe-west1.gcp.commercetools.com/proxy/ctp/${projectKey}/orders`, {
  method: 'GET',
  headers: { Accept: 'application/json' },
  credentials: 'include', // <-- this will send along the cookie "mcAccessToken"
});

The Merchant Center applications have access to 2 built-in clients:

a REST client that is a wrapper to the commercetools JS SDK, available from the @commercetools-frontend/sdk package
an Apollo GraphQL client, which is automatically configured from the <ApplicationShell> React component

Both clients are configured to send the cookies with each request.