API Gateway stage variables reference for REST APIs in API Gateway
You can use API Gateway stage variables in the following cases.
Parameter mapping expressions
A stage variable can be used in a parameter mapping expression for an API method's request or response
header parameter, without any partial substitution. In the following example, the stage variable is referenced
without the $ and the enclosing {...}.
-
stageVariables.<variable_name>
Mapping templates
A stage variable can be used anywhere in a mapping template, as shown in the following examples.
-
{ "name" : "$stageVariables.<variable_name>"} -
{ "name" : "${stageVariables.<variable_name>}"}
HTTP integration URIs
A stage variable can be used as part of an HTTP integration URL, as shown in the following examples:
-
A full URI without protocol –
http://${stageVariables.<variable_name>} -
A full domain –
http://${stageVariables.<variable_name>}/resource/operation -
A subdomain –
http://${stageVariables.<variable_name>}.example.com/resource/operation -
A path –
http://example.com/${stageVariables.<variable_name>}/bar -
A query string –
http://example.com/foo?q=${stageVariables.<variable_name>}
AWS integration URIs
A stage variable can be used as part of AWS URI action or path components, as shown in the following example.
-
arn:aws:apigateway:<region>:<service>:${stageVariables.<variable_name>}
AWS integration URIs (Lambda functions)
A stage variable can be used in place of a Lambda function name, or version/alias, as shown in the following examples.
-
arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:${stageVariables.<function_variable_name>}/invocations -
arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:<function_name>:${stageVariables.<version_variable_name>}/invocations
Note
To use a stage variable for a Lambda function, the function must be in the same account as the API. Stage variables don't support cross-account Lambda functions.
Amazon Cognito user pool
A stage variable can be used in place of a Amazon Cognito user pool for a COGNITO_USER_POOLS authorizer.
-
arn:aws:cognito-idp:<region>:<account_id>:userpool/${stageVariables.<variable_name>}
AWS integration credentials
A stage variable can be used as part of AWS user/role credential ARN, as shown in the following example.
-
arn:aws:iam::<account_id>:${stageVariables.<variable_name>}
