Enabling CORS support for an API

You can enable cross-origin resource sharing (CORS) support for your API. CORS allows embedded scripts in a web page to call the API across domain boundaries.

To enable CORS support for an API, complete the following steps:

1. In the navigation pane, click Develop, then select the APIs tab.
2. To enable CORS support for an existing API, click the title of the API that you want to work with.

   To create a new API before enabling CORS, see Creating an API definition.

3. Select API Setup. Scroll to the Lifecycle section, and select CORS.
4. Click Save to save your changes.
5. Optional: To implement your own CORS solution using custom OPTIONS operations, complete the following steps:
   1. Add the following headers to your HTTP responses:

      Access-Control-Allow-Origin: https://<portalhostname>
      Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept 

      Where <portalhostname> is your Developer Portal host name.
   2. Optional: You can proxy your API through API Connect as an enforced invoke API so that CORS is handled automatically.
   Important:

   • If you implement your own CORS solution, you must disable the CORS option described in step 3
   • CORS preflight requests are sent by using the HTTP OPTIONS method. Therefore, if you require these requests to be handled by the API Connect gateway then you must enable the OPTIONS method for all APIs that will handle preflight requests; see Defining Paths for a REST API.
   • OPTIONS requests are counted as API calls against any configured rate limit. Note that you can apply rate limits to individual operations; see Defining rate limits for an API operation.
6. Optional: If CORS is enabled, you can customize the CORS support for the API on the DataPower® API Gateway by adding, to the cors configuration in the API YAML definition on the Source tab, a policy that contains CORS rules, as follows:

   x-ibm-configuration:
      .
      .
      .
     cors
       enabled: true
       policy
         -
           allow-origin:
                .
                .
                .
             list of Origin headers that will be accepted
                .
                .
                .
           allow-credentials: boolean that controls whether Access-Control-Allow-Credentials: true is returned in the CORS response
         -
             .
             .
             .
           further CORS rules
             .
             .
             .

   The following conditions apply:

   • You can have at most one policy entry. The policy is applied only if CORS is enabled.
   • A policy can have zero or more CORS rules. If it has no rules then all CORS requests are denied, meaning that any API calls that contain CORS headers or that send a CORS preflight request will fail with a 403 Forbidden error.
   • A CORS rule must have at least one Origin header in an allow-origin list.
   • A CORS rule can have zero or one allow-credentials: entries, set to either true or false; if omitted, the default value is false. If the value is false, the CORS response will not contain an Access-Control-Allow-Credentials header. The gateway never returns Access-Control-Allow-Credentials: false; it either returns a value of true or does not return the header at all, in accordance with the CORS standard: see https://fetch.spec.whatwg.org/#http-new-header-syntax.
   • Wildcards are not supported for the allow-origin values, you can enter only literal strings. Origins must follow the schema described in the fetch standard at https://fetch.spec.whatwg.org/#origin-header so, for example, port values can be entered but are optional.

   Example

   The following example has three rules:

   • Accept an Origin header of https://example.com, and return Access-Control-Allow-Credentials: true in the CORS response.
   • Accept an Origin header of http://domain.com. No Access-Control-Allow-Credentials header will be returned in the response.
   • Accept any of the following Origin headers:
     • http://example2.com
     • http://example3.com
     • http://example4.com
     No Access-Control-Allow-Credentials header will be returned in the response.

     cors:
       enabled: true
       policy:
         -
           allow-origin:
             - 'https://example.com'
           allow-credentials: true
         -
           allow-origin:
             - 'http://domain.com'
         -
           allow-origin:
             - 'http://example2.com'
             - 'http://example3.com'
             - 'http://example4.com'