How do I send custom security headers through API Gateway for Lambda proxy or non-proxy integrations?

Resolution

To add custom security headers in API Gateway responses, follow the method for your integration type.

Note: The following resolution applies only to API Gateway REST APIs. HTTP APIs don't support method response or integration response mappings.

Lambda proxy integrations

For Lambda proxy integrations, API Gateway sends the request and response between the client and the integrated Lambda function without modifications. To send custom security headers from an API Gateway API to a Lambda function, you must modify the function source code.

Complete the following steps:

1. Open the API Gateway console.

2. In the navigation pane, choose APIs, and then select your REST API.

3. Choose Create method.

4. In the Create Method pane, take the following actions:
   For Method type, choose your method type.
   For Integration type, choose Lambda function.
   Confirm that you turned on the Lambda proxy integration.
   For Lambda function, select your Lambda function.
   Choose Create method.

5. In the Integration Request pane, select your Lambda function.

6. For Code source, replace the function's code with either the following Python code or Node.js code in the code editor.
   Python 3.14 and later:

   def lambda_handler(event, context):
   return {
       'statusCode': 200,
       'headers': {
           "Strict-Transport-Security": "max-age=100000",
           "X-Frame-Options": "DENY",
           "X-Content-Type-Options": "nosniff",
           "Content-Security-Policy": "default-src 'self'"
        },
       'body': json.dumps("Hello from Lambda with security headers!")
   }

   Node.js 14 and later:

   exports.handler = async (event) => {
       const response = {
           statusCode: 200,
           headers: {
               'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
               'Content-Security-Policy': "default-src 'self'",
               'X-Frame-Options': 'DENY',
               'X-Content-Type-Options': 'nosniff'
           },
           body: JSON.stringify('Hello from Lambda with security headers!')
       };
       return response;
   };

7. Choose Deploy.

Non-proxy integrations

To send custom security headers through non-proxy, or custom, integrations such as AWS service and HTTP integration types, create a mapping template or method response.

Create a mapping template

Complete the following steps:

1. Open the API Gateway console.

2. In the navigation pane, choose APIs, and then select your REST API.

3. In the Create Method pane, enter your method type and integration type, and then choose Create method.

4. In the Integration Request pane, choose Edit.

5. Expand Mapping templates, and then choose Add mapping template.

6. For Content type, enter your content type. For example, application/json.

7. In the Template body editor, enter the following mapping template:

   #set($headersToReturn = {  
     "Strict-Transport-Security": "max-age=31536000; includeSubDomains"  
   })#foreach($header in $headersToReturn.keySet())  #set($context.responseOverride.header\[$header\] = $headersToReturn\[$header\])#end

8. Choose Save.

9. Choose Deploy API.

Create a method response

Complete the following steps:

1. Open the API Gateway console.
2. In the navigation pane, choose APIs, and then choose your REST API.
3. In the Method response pane, choose Edit.
4. For Header name, choose Add header.
5. Enter the name of the custom header that you want to return, for example Strict-Transport-Security.
6. Choose Add header to add another header that you want to return, for example Content-Security-Policy.
7. Choose Save.
8. In the Integration Request pane, choose Edit.
9. For Header mappings, enter the mapping values for your headers, for example max-age=100000 and self.
10. Choose Save, and then choose Deploy API.

Test your setup

To confirm that the security custom headers are included in the response, run the following curl command to invoke your REST API:

curl -v https://your-api-id.execute-api.your-region.amazonaws.com/your-stage-name

Note: Replace your-api-id with your REST API, your-region with your AWS Region, and your-stage-name with your stage name.

Related information

How do I pass custom headers through API Gateway to a Lambda function with Lambda custom (non-proxy) integration?

Mapping template transformations for REST APIs in API Gateway

How do I resolve HTTP 502 errors from API Gateway REST APIs with Lambda proxy integration?

Tutorial: Create a REST API with a Lambda non-proxy integration