bug: Step Functions apigateway:invoke: list-valued Headers reach API Gateway as a bracketed string (["v"] → [v])

[k-rooot]

Current behavior

In a Step Functions task using arn:aws:states:::apigateway:invoke, header values given in the list form documented by AWS ("Headers": {"x-api-key": ["value"]}) arrive at API Gateway as the string representation of the list:

Sent in Parameters.Headers	Received by API Gateway
{"x-single": ["value1"]}	x-single: [value1]
{"x-multi": ["a", "b"]}	x-multi: [a,b]
{"x-single": "value1"} (plain string)	x-single: value1

A practical consequence: an API key passed in the documented list form ("x-api-key": ["<key>"]) never matches, and a REST API method with apiKeyRequired: true answers 403 Forbidden. The LocalStack log shows Error raised during invocation: INVALID_API_KEY. The same key sent as a plain string is accepted.

Expected behavior

As on AWS: each list element is sent as a value of that header, so ["value1"] arrives as value1 and ["a", "b"] arrives as two values (a,b when combined). The AWS documentation for the API Gateway integration states that "HTTP headers allow a list of values associated with the same key" and shows "Headers": {"key": ["value1", "value2"]} (https://docs.aws.amazon.com/step-functions/latest/dg/connect-api-gateway.html).

How are you starting LocalStack?

With a docker run command:

docker run --rm -p 127.0.0.1:4566:4566 -e LOCALSTACK_AUTH_TOKEN localstack/localstack-pro:2026.8.1

Steps to reproduce

Self-contained script (boto3 only): it creates a MOCK REST API that echoes two request headers, then calls it from a state machine with the list form and with the string form. Script:

"""Step Functions apigateway:invoke sends list-valued Headers as a bracketed string.

Run against LocalStack on http://localhost:4566 (pip install boto3).
"""
import json
import time

import boto3

KW = dict(endpoint_url="http://localhost:4566", region_name="us-east-1",
          aws_access_key_id="test", aws_secret_access_key="test")
apigw = boto3.client("apigateway", **KW)
sfn = boto3.client("stepfunctions", **KW)

# A MOCK REST API that echoes two request headers back in its body.
api = apigw.create_rest_api(name="header-echo")["id"]
root = next(r["id"] for r in apigw.get_resources(restApiId=api)["items"] if r["path"] == "/")
res = apigw.create_resource(restApiId=api, parentId=root, pathPart="echo")["id"]
apigw.put_method(restApiId=api, resourceId=res, httpMethod="POST", authorizationType="NONE")
apigw.put_integration(restApiId=api, resourceId=res, httpMethod="POST", type="MOCK",
                      requestTemplates={"application/json": '{"statusCode": 200}'})
apigw.put_method_response(restApiId=api, resourceId=res, httpMethod="POST", statusCode="200")
apigw.put_integration_response(
    restApiId=api, resourceId=res, httpMethod="POST", statusCode="200",
    responseTemplates={"application/json":
                       '{"single": "$input.params(\'x-single\')", "multi": "$input.params(\'x-multi\')"}'})
apigw.create_deployment(restApiId=api, stageName="dev")

try:
    for label, headers in [("list form (as documented)", {"x-single": ["value1"], "x-multi": ["a", "b"]}),
                           ("string form", {"x-single": "value1"})]:
        definition = {"StartAt": "Call", "States": {"Call": {
            "Type": "Task", "Resource": "arn:aws:states:::apigateway:invoke", "End": True,
            "Parameters": {"ApiEndpoint": f"{api}.execute-api.us-east-1.localhost.localstack.cloud",
                           "Method": "POST", "Stage": "dev", "Path": "echo", "Headers": headers,
                           "RequestBody": {}}}}}
        arn = sfn.create_state_machine(name=f"header-echo-{len(headers)}", definition=json.dumps(definition),
                                       roleArn="arn:aws:iam::000000000000:role/any")["stateMachineArn"]
        execution = sfn.start_execution(stateMachineArn=arn, input="{}")["executionArn"]
        while (described := sfn.describe_execution(executionArn=execution))["status"] == "RUNNING":
            time.sleep(0.5)
        body = json.loads(described.get("output") or "{}").get("ResponseBody", described.get("cause"))
        print(f"{label}: sent {headers} -> API received {body}")
        sfn.delete_state_machine(stateMachineArn=arn)
finally:
    apigw.delete_rest_api(restApiId=api)

Output:

list form (as documented): sent {'x-single': ['value1'], 'x-multi': ['a', 'b']} -> API received {'single': '[value1]', 'multi': '[a,b]'}
string form: sent {'x-single': 'value1'} -> API received {'single': 'value1', 'multi': ''}

The result is the same whether AuthType is omitted, NO_AUTH, IAM_ROLE or RESOURCE_POLICY, and whether Path has a leading /.

Environment

• OS: macOS 26 (Apple silicon), Docker Desktop; also seen on Amazon Linux 2 x86_64
• LocalStack: localstack/localstack-pro:2026.7.5 and localstack/localstack-pro:2026.8.1

Anything else?

Workaround: write single-value headers as plain strings in the state machine definition. That only works where the definition can be changed, and multi-value headers have no workaround.

[bentsku]

Hello @k-rooot and thanks a lot for the report!

The issue should be fixed in the latest dev release (localstack/localstack-pro:dev). Could you try pulling it and see if that fixes your issue?
The fix will then be part of the next monthly release 2026.10.0 coming up in this month.

Thanks again for the report! Let me know if it still doesn't work.

[bentsku]

Hello @k-rooot and thanks for the report. The fix is available in the 2026.10.0 version now, so I'll close the issue. Let me know if you still encounter the issue and we can re-open. Thanks again!