CORS support

For security purposes, web browsers implement the same-domain policy, which prevents JavaScript on a page served from one domain from accessing resources on another domain. In some cases, you may want to selectively override this policy to allow specific domains to access data on your stores.

Note: You can allow access to Admin and Agent endpoints as well. See Configure CORS support for the Admin or Agent endpoints below for information.

To enable a browser displaying a page on an external domain to access resources in your storefront environment, Commerce supports CORS (cross-origin resource sharing), which is a standard mechanism for implementing cross-domain requests. For a detailed description of CORS, see:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS

You configure CORS support in Commerce by explicitly specifying the external domains whose pages are permitted to access data on your sites. When a cross-domain request is submitted, the web browser is responsible for determining if access is permitted. In some cases, prior to sending the actual request, the browser first sends an OPTIONS method preflight request with headers that specify the domain that the request originates from and the expected HTTP method. In this situation, Commerce responds to the preflight request by indicating whether the actual request can be sent.

You specify the domains and methods permitted to access a specific site by using the PUT /ccadmin/v1/sites/{siteID} endpoint to set the value of the allowedOriginMethods property on the corresponding site object. For example, the following call enables cross-domain access to the siteUS site from two external domains and specifies which HTTP methods are permitted from each domain:

PUT /ccadmin/v1/sites/siteUS  HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en

{
    "properties": {
        "allowedOriginMethods": {
            "http://www.example1.com": "GET,OPTIONS",
            "http://www.example2.com": "GET,PUT,POST,OPTIONS"
         }
    }
}

After setting the value of allowedOriginMethods on the site object, publish the changes so they apply to the live context.

Note that the domain entries for the allowedOriginMethods property must be fully qualified, and cannot include wildcards. You must provide a separate entry for each domain or subdomain you want to enable access for. For example, if you want to provide CORS access to a domain named www.example1.com that has subdomains named shoes.example1.com and shirts.example1.com, you need to create three entries.

Also, even if you enable cross-domain requests, access to a resource from an allowed domain may require authentication. For example, calls to the Admin API endpoints require authentication, as described in REST API Authentication.

Configure CORS support for the Admin or Agent endpoints

You can enable external domains to access the Admin and Agent endpoints by using PUT /ccadmin/v1/merchant/adminConfiguration (for configuring access to the Admin API) or PUT /ccadmin/v1/merchant/agentConfiguration (for access to the Agent API). Each of these calls has an associated allowedOriginMethods property for specifying the domains and HTTP methods.

For example, the following call enables access to the Admin API from two external domains:

PUT /ccadmin/v1/merchant/adminConfiguration  HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en

{
    "properties": {
        "allowedOriginMethods": {
            "http://www.example3.com": "GET,POST,OPTIONS",
            "http://www.example4.com": "GET,PUT,POST,DELETE,OPTIONS"
         }
    }
}

Note that for the Admin and Agent endpoints, the allowedOriginMethods values take effect in the live context immediately. You do not need to publish the changes.