Amazon API Gateway
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Amazon API Gateway Stage Variables Reference

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, e.g., http://${stageVariables.<variable_name>}

  • A full domain: e.g., http://${stageVariables.<variable_name>}/resource/operation

  • A subdomain: e.g., http://${stageVariables.<variable_name>}.example.com/resource/operation

  • A path, e.g., http://example.com/${stageVariables.<variable_name>}/bar

  • A query string, e.g., 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::<account_id>:function:${stageVariables.<function_variable_name>}/invocations

  • arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda::<account_id>:function:<function_name>:${stageVariables.<version_variable_name>}/invocations

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