Proxy to External API

This feature only allows for an external server to check that requests come from authenticated users. It does not provide a way for the server to perform user access validation and more fine grained permission checks. If you are interested in these functionalities, let us know and open a support issue.

Developing Custom Applications might require you to have your own backend server, for several reasons: storing sensitive credentials for third-party services, performing custom server logic, etc.

If that's the case, you're probably facing a problem: how do you authenticate requests to your API?

Merchant Center applications can make authenticated requests using the proxy endpoints to the underlying APIs that are configured and supported for the Merchant Center. Requests are authenticated via the mcAccessToken stored in a secure cookie, which is set only for domains.

Since your backend server is hosted on a different domain, you can't send authenticated requests to your server from your Custom Application. Well, you can but you don't know if the request comes from an authenticated user or not.

Validating authenticated requests

To be able to validate that the request comes from an authenticated user, we implemented a mechanism to allow your server to verify the validity of the mcAccessToken.

Requests to your backend server should be configured as following:

  • send the request to /proxy/forward-to endpoint of the Merchant Center API Gateway.
  • define the original request URL to your backend server as an HTTP header X-Forward-To.
fetch(``, {
method: 'GET',
headers: {
Accept: 'application/json',
'X-Forward-To': '',
credentials: 'include',

The request will be then validated from the Merchant Center API Gateway and proxied to the specified HTTP header, sending alongside an Authorization: Bearer <token> HTTP header, in the form of a JWT.

For security reasons, the exchanged JWT has an expiration date of 60 seconds, as the token should only be used to verify that the request is authorized.

Using JSON Web Key Set endpoint

At this point, your backend server will receive the request with the Authorization header, which you can use to validate that the JWT is valid. The validation is performed by using the /.well-known/jwks.json endpoint exposed by the Merchant Center API Gateway. You can read more about JWKS here and here.

The endpoint exposes a public key which can be used to verify the JWT signature, according to the OIDC spec. We also expose a /.well-known/openid-configuration discovery endpoint.

If your backend server is implemented with JavaScript, we recommend to use the express-jwt package that acts as an Express middleware to automatically verify the authentication request.

const express = require('express');
const jwt = require('express-jwt');
const jwksRsa = require('jwks-rsa');
// Initialize the app.
const app = express();
// The issuer refers to the Merchant Center API Gateway URL.
const issuer = '';
// The audience refers to the forwarded target URL (same value as in `X-Forward-To` header)
const audience = '';
// Dynamically provide a signing key based on the kid in the header
// and the singing keys provided by the JWKS endpoint
secret: jwksRsa.expressJwtSecret({
cache: true,
rateLimit: true,
jwksRequestsPerMinute: 5,
// The JWKS endpoint is also available from the discovery endpoint
// `${audience}/.well-known/openid-configuration`
// in case you wish to retrieve it programmatically.
jwksUri: `${issuer}/.well-known/jwks.json`,
// Validate the audience and the issuer.
algorithms: ['RS256'],
Developer Center
HTTP APIGraphQL APIBETAPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & Export ToolsSUNRISE Starter FrontendsTutorialsFAQ
Merchant Center
DocumentationRelease Notes
Copyright © 2020 commercetools