aws_apigateway: Allow StepFunctionsIntegration to include specific headers

[WtfJoke]

Describe the feature

Allow StepFunctionExecutionIntegrationOptions#headers to accept a list of header names in addition to a boolean (or if limited by JSII, introduce a new property headerNames).

The generated request-mapping template should forward only the specified headers.
While headers: true could retain its current behaviour of forwarding all headers.

Use Case

We need to forward a single non-sensitive header, user-id, to the Step Functions execution input. Using headers: true forwards all request headers, including sensitive values such as Authorization and Cookie, which may then appear in Step Functions execution history and logs, which I would like to avoid.

The alternative is to copy the existing template and adapt or write my own template. Dealing with vtl template is something we usually try to avoid.

Selective header forwarding would support least-privilege data handling, avoid accidental exposure of sensitive headers, and remove the need to maintain a custom Velocity mapping template.

Proposed Solution

Keep the existing headers?: boolean property for backward compatibility and add a separate JSII-compatible property for selective forwarding in https://github.com/aws/aws-cdk/blob/v2.263.0/packages/aws-cdk-lib/aws-apigateway/lib/integrations/stepfunctions.ts#L18:

export interface StepFunctionsExecutionIntegrationOptions extends IntegrationOptions {
  /**
   * Includes all request headers in the Step Functions execution input.
   */
  readonly headers?: boolean;

  /**
   * Includes only the named request headers in the execution input.
   * Mutually exclusive with `headers: true`.
   */
  readonly headerNames?: string[];
}

Other Information

The feature request could also work with a similar pattern with querystring (and maybe path but I don't have any use cases for allowing only specific paths)

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

2.261.0

AWS CDK CLI version

npx cdk --version

Environment details (OS name and version, etc.)

macos 26.6.1

[pahud]

Hi @WtfJoke,

┌────────────────────────────────────────────────────────────┐
│ 🔴 Reported State                                          │
│ headers: true forwards ALL headers (incl. Authorization)   │
│ into SFN execution input; no selective option              │
└─────────────────────────────┬──────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────┐
│ 🔍 Root Cause                                              │
│ Boolean-only option; VTL loops over every header key       │
│ aws-apigateway/lib/integrations/stepfunctions.vtl#L19-L28  │
└─────────────────────────────┬──────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────┐
│ 🟢 Suggested Fix                                           │
│ Add headerNames?: string[] (allowlist), keep headers:      │
│ boolean for back-compat; interim: requestTemplates override│
└────────────────────────────────────────────────────────────┘

This is a feature request rather than a bug, so no reproduction was attempted — verified the limitation directly in source. headers is a plain boolean, and the generated VTL iterates every header key with no filter:

aws-cdk/packages/aws-cdk-lib/aws-apigateway/lib/integrations/stepfunctions.vtl

Lines 19 to 28 in d81d2d6

	#if ($includeHeaders)
	#set($inputString = "$inputString, @@header@@:{")
	#foreach($paramName in $allParams.header.keySet())
	#set($inputString = "$inputString @@$paramName@@: @@$util.escapeJavaScript($allParams.header.get($paramName))@@")
	#if($foreach.hasNext)
	#set($inputString = "$inputString,")
	#end
	#end
	#set($inputString = "$inputString }")

Interim workaround available today: requestTemplates you pass in overrides the generated one entirely, so you can copy stepfunctions.vtl, add your own allowlist filter, and pass it through — no fork of the integration needed.

Your headerNames?: string[] proposal is the right shape (JSII rules out boolean | string[]). A PR should add mutual-exclusion validation against headers: true and case-insensitive header matching. Welcome a PR — scope it to headers first, treat querystring as a follow-up.