Amazon API Gateway
Developer Guide

Manage API Gateway API Deployment with Stage Variables

Stage variables are name-value pairs that you can define as configuration attributes associated with a deployment stage of an API. They act like environment variables and can be used in your API setup and mapping templates.

For example, you can define a stage variable in a stage configuration, and then set its value as the URL string of an HTTP integration for a method in your API. Later, you can reference the URL string using the associated stage variable name from the API setup. This way, you can use the same API setup with a different endpoint at each stage by resetting the stage variable value to the corresponding URLs. You can also access stage variables in the mapping templates, or pass configuration parameters to your AWS Lambda or HTTP back end.

For more information about mapping templates, see Request and Response Payload-Mapping Reference.

Use Cases

With deployment stages in API Gateway, you can manage multiple release stages for each API, such as alpha, beta, and production. Using stage variables you can configure an API deployment stage to interact with different back-end endpoints. For example, your API can pass a GET request as an HTTP proxy to the back-end web host (for example, In this case, the back-end web host is configured in a stage variable so that when developers call your production endpoint, API Gateway calls When you call your beta endpoint, API Gateway uses the value configured in the stage variable for the beta stage, and calls a different web host (for example, Similarly, stage variables can be used to specify a different AWS Lambda function name for each stage in your API.

You can also use stage variables to pass configuration parameters to a Lambda function through your mapping templates. For example, you may want to re-use the same Lambda function for multiple stages in your API, but the function should read data from a different Amazon DynamoDB table depending on which stage is being called. In the mapping templates that generate the request for the Lambda function, you can use stage variables to pass the table name to Lambda.


To use a stage variable to customize the HTTP integration endpoint, you must first configure a stage variable of a specified name, e.g., url, and then assign it a value, e.g., Next, from your method configuration, set up an HTTP proxy integration, and instead of entering the endpoint's URL, you can tell API Gateway to use the stage variable value, http://${stageVariables.url}. This value tells API Gateway to substitute your stage variable ${} at runtime, depending on which stage your API is running. You can reference stage variables in a similar way to specify a Lambda function name, an AWS Service Proxy path, or an AWS role ARN in the credentials field.

When specifying a Lambda function name as a stage variable value, you must configure the permissions on the Lambda function manually. You can use the AWS Command Line Interface to do this.

aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal --statement-id apigateway-access --action lambda:InvokeFunction

The following example assigns API Gateway permission to invoke a Lambda function named helloWorld hosted in the US West (Oregon) region of an AWS account on behalf of the API method.

arn arn:aws:execute-api:us-west-2:123123123123:bmmuvptwze/*/GET/hello

Here is the same command using the AWS CLI.

aws lambda add-permission --function-name arn:aws:lambda:us-east-1:123123123123:function:helloWorld --source-arn arn:aws:execute-api:us-west-2:123123123123:bmmuvptwze/*/GET/hello --principal --statement-id apigateway-access --action lambda:InvokeFunction