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:'request-originating server addresses' header in at least its 200 response. You can replace the static value of specific request-originating server addresses with * to indicate any servers. However, you should be careful of enabling such a broad support and do so only when you fully understand the consequences.

With Lambda, AWS or HTTP integrations, you can leverage API Gateway to set up the required headers using the method response and integration response. For Lambda or HTTP proxy integrations, you can still set up the required OPTIONS response headers in API Gateway. However, you must rely on the back end to return the Access-Control-Allow-Origin headers because the integration response is disabled for the proxy integration.

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 an 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

    Note

    When applying the above instructions to the ANY method in a proxy integration, any applicable CORS headers will not be set. Instead, you rely on the integration backend to return the applicable CORS headers, such as Access-Control-Allow-Origin

  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.

As with any updates of your API, you must deploy or redeploy the API for the new settings to take effect.

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.

Copy
/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.

    Copy
    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:

    Copy
    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 : "'*'"