Menu
Amazon API Gateway
Developer Guide

Enable CORS for an API Gateway Resource

When your API's resources receive requests from a domain other than the API's own domain, you must enable cross-origin resource sharing (CORS) for selected methods on the resource. This amounts to having your API respond to the OPTIONS preflight request with at least the following CORS-required response headers:

  • Access-Control-Allow-Methods

  • Access-Control-Allow-Headers

  • Access-Control-Allow-Origin

In API Gateway you enable CORS by setting up an OPTIONS method with the mock integration type to return the preceding response headers (with static values discussed in the following) as the method response headers. In addition, the actual CORS-enabled methods must also return the Access-Control-Allow-Origin:'*' header in at least its 200 response.

Tip

You must set up an OPTIONS method to handle preflight requests to support CORS. However, OPTIONS methods are optional if 1) an API resource exposes only the GET, HEAD or POST methods and 2) the request payload content type is application/x-www-form-urlencoded, multipart/form-data or text/plain and 3) the request does not contain any custom headers. When possible, we recommend to use OPTIONS method to enable CORS in your API.

This section describes how to enable CORS for a method in API Gateway using the API Gateway console or the API Gateway Import API.

Prerequisites

Enable CORS on a Resource Using the API Gateway Console

  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. In the API Gateway console, choose an API under APIs.

  3. Choose a resource under Resources. This will enable CORS for all the methods on the resource.

    Alternatively, you could choose a method under the resource to enable CORS for just this method.

  4. Choose Enable CORS from the Actions drop-down menu.

    Choose Enable CORS

  5. In the Enable CORS form, do the following:

    1. In the Access-Control-Allow-Headers input field, type a static string of a comma-separated list of headers that the client must submit in the actual request of the resource. Use the console-provided header list of 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token' or specify your own headers.

    2. Use the console-provided value of '*' as the Access-Control-Allow-Origin header value to allow access requests from all domains, or specify a named domain to all access requests from the specified domain.

    3. Choose Enable CORS and replace existing CORS headers.

    Choose which headers are allowed

  6. In Confirm method changes, choose Yes, overwrite existing values to confirm the new CORS settings.

    Confirm overwrite of existing values

After CORS is enabled on the GET method, an OPTIONS method is added to the resource, if it is not already there. The 200 response of the OPTIONS method is automatically configured to return the three Access-Control-Allow-* headers to fulfill preflight handshakes. In addition, the actual (GET) method is also configured by default to return the Access-Control-Allow-Origin header in its 200 response as well. For other types of responses, you will need to manually configure them to return Access-Control-Allow-Origin' header with '*' or specific origin domain names, if you do not want to return the Cross-origin access error.

Enable CORS for a Resource Using the API Gateway Import API

If you are using the API Gateway Import API, you can set up CORS support using a Swagger file. You must first define an OPTIONS method in your resource that returns the required headers.

Note

Web browsers expect Access-Control-Allow-Headers, and Access-Control-Allow-Origin headers to be set up in each API method that accepts CORS requests. In addition, some browsers first make an HTTP request to an OPTIONS method in the same resource, and then expect to receive the same headers.

The following example creates an OPTIONS method and specifies mock integration. For more information, see Configure Mock Integration for a Method.

/users 
   options:
      summary: CORS support
      description: |
        Enable CORS by returning correct headers
      consumes:
        - application/json
      produces:
        - application/json
      tags:
        - CORS
      x-amazon-apigateway-integration:
        type: mock
        requestTemplates:
          application/json: |
            {
              "statusCode" : 200
            }
        responses:
          "default":
            statusCode: "200"
            responseParameters:
              method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
              method.response.header.Access-Control-Allow-Methods : "'*'"
              method.response.header.Access-Control-Allow-Origin : "'*'"
            responseTemplates:
              application/json: |
                {}
      responses:
        200:
          description: Default response for CORS method
          headers:
            Access-Control-Allow-Headers:
              type: "string"
            Access-Control-Allow-Methods:
              type: "string"
            Access-Control-Allow-Origin:
              type: "string"

Once you have configured the OPTIONS method for your resource, you can add the required headers to the other methods in the same resource that need to accept CORS requests.

  1. Declare the Access-Control-Allow-Origin and Headers to the response types.

          responses:
            200:
              description: Default response for CORS method
              headers:
                Access-Control-Allow-Headers:
                  type: "string"
                Access-Control-Allow-Methods:
                  type: "string"
                Access-Control-Allow-Origin:
                  type: "string"
  2. In the x-amazon-apigateway-integration tag, set up the mapping for those headers to your static values:

            responses:
              "default":
                statusCode: "200"
                responseParameters:
                  method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'"
                  method.response.header.Access-Control-Allow-Methods : "'*'"
                  method.response.header.Access-Control-Allow-Origin : "'*'"