Introduction

To make API Gateway invoke a specific Lambda alias, you point the integration at the alias-qualified Lambda ARN instead of the unqualified function ARN. That way the API stays stable while the alias can move between published Lambda versions such as dev, staging, or prod.

Why use an alias at all

A Lambda alias is a named pointer to a published version of a function. Instead of wiring API Gateway directly to $LATEST or a raw version number, you can target an alias such as prod.

That gives you a cleaner deployment flow:

• publish a new Lambda version
• move the alias to that version
• leave API Gateway unchanged

This is one of the main reasons aliases exist.

The ARN must include the alias

A normal Lambda function ARN looks like this:

arn:aws:lambda:us-east-1:123456789012:function:my-function

An alias-qualified ARN adds the alias name at the end:

arn:aws:lambda:us-east-1:123456789012:function:my-function:prod

That suffix is the key. If API Gateway points at the unqualified ARN, it is not pinned to the alias.

Example with AWS CLI

First publish a version and create the alias:

1aws lambda publish-version --function-name my-function
2
3aws lambda create-alias \
4  --function-name my-function \
5  --name prod \
6  --function-version 5

Then configure API Gateway to use the alias-qualified invocation target. In REST API integration URIs, the Lambda ARN inside the API Gateway URI must include the alias:

arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:my-function:prod/invocations

If you are using infrastructure as code, that alias-qualified function ARN is what you should reference.

Do not forget Lambda permission

API Gateway also needs permission to invoke that alias. The permission statement should target the alias-qualified function name as well:

1aws lambda add-permission \
2  --function-name arn:aws:lambda:us-east-1:123456789012:function:my-function:prod \
3  --statement-id apigateway-prod \
4  --action lambda:InvokeFunction \
5  --principal apigateway.amazonaws.com \
6  --source-arn "arn:aws:execute-api:us-east-1:123456789012:api-id/*/*/*"

If permission is granted only on the base function but your tooling expects alias-specific policy behavior, you can end up with confusing invocation failures.

Infrastructure as code example

In CloudFormation or SAM, the pattern is the same: the integration points at the alias ARN.

1MyAlias:
2  Type: AWS::Lambda::Alias
3  Properties:
4    FunctionName: !Ref MyFunction
5    FunctionVersion: !GetAtt MyVersion.Version
6    Name: prod

The API integration should reference MyAlias rather than the raw function resource when the goal is alias-specific routing.

Why this is better than using $LATEST

Pointing API Gateway at $LATEST mixes deployment and runtime behavior in a way that makes releases harder to control. With aliases, you get a stable endpoint and a controlled promotion step.

That also makes rollbacks easier. If a release goes bad, move the alias back to the previous version instead of editing API Gateway itself.

Common Pitfalls

• Pointing API Gateway at the unqualified Lambda ARN and assuming the alias will still be used.
• Updating the alias but forgetting the API integration still targets the base function.
• Granting invoke permission to the wrong function or alias ARN.
• Using $LATEST in production workflows instead of published versions plus aliases.
• Confusing Lambda versions with aliases. A version is immutable, while an alias is a movable pointer.

Summary

• To target a specific Lambda alias, use the alias-qualified ARN in the API Gateway integration.
• The ARN must end with the alias name, such as :prod.
• Grant API Gateway invoke permission against the alias-qualified function target.
• Aliases make deployments and rollbacks cleaner than pointing at $LATEST.
• The core idea is simple: API Gateway should integrate with the alias, not just the base Lambda function.