Controlling access to API Gateway APIs

Lambda authorizers – A Lambda authorizer (formerly known as a custom authorizer) is a Lambda function that you provide to control access to your API. When your API is called, this Lambda function is invoked with a request context or an authorization token that the client application provides. The Lambda function responds whether the caller is authorized to perform the requested operation.

Both the AWS::Serverless::HttpApi and AWS::Serverless::Api resource types support Lambda authorizers.

For more information about Lambda authorizers with AWS::Serverless::HttpApi, see Working with Amazon Lambda authorizers for HTTP APIs in the API Gateway Developer Guide. For more information about Lambda authorizers with AWS::Serverless::Api, see Use API Gateway Lambda authorizers in the API Gateway Developer Guide.

For examples of Lambda authorizers for either resource type, see Lambda authorizer examples.

IAM permissions – You can control who can invoke your API using Amazon Identity and Access Management (IAM) permissions. Users calling your API must be authenticated with IAM credentials. Calls to your API succeed only if there is an IAM policy attached to the IAM user that represents the API caller, an IAM group that contains the user, or an IAM role that the user assumes.

Only the AWS::Serverless::Api resource type supports IAM permissions.

For more information, see Control access to an API with IAM permissions in the API Gateway Developer Guide. For an example, see IAM permission example.

Amazon Cognito user pools – Amazon Cognito user pools are user directories in Amazon Cognito. A client of your API must first sign in a user to the user pool and obtain an identity or access token for the user. Then the client calls your API with one of the returned tokens. The API call succeeds only if the required token is valid.

The AWS::Serverless::Api resource type supports Amazon Cognito user pools. The AWS::Serverless::HttpApi resource type supports the use of Amazon Cognito as a JWT issuer.

For more information, see Control access to a REST API using Amazon Cognito user pools as authorizer in the API Gateway Developer Guide. For an example, see Amazon Cognito user pool example.

API keys – API keys are alphanumeric string values that you distribute to application developer customers to grant access to your API.

Only the AWS::Serverless::Api resource type supports API keys.

For more information about API keys, see Creating and using usage plans with API keys in the API Gateway Developer Guide. For an example of API keys, see API key example.

Resource policies – Resource policies are JSON policy documents that you can attach to an API Gateway API. Use resource policies to control whether a specified principal (typically an IAM user or role) can invoke the API.

Only the AWS::Serverless::Api resource type supports resource policies as a mechanism for controlling access to API Gateway APIs.

For more information about resource policies, see Controlling access to an API with API Gateway resource policies in the API Gateway Developer Guide. For an example of resource policies, see Resource policy example.

OAuth 2.0/JWT authorizers – You can use JWTs as a part of OpenID Connect (OIDC) and OAuth 2.0 frameworks to control access to your APIs. API Gateway validates the JWTs that clients submit with API requests, and allows or denies requests based on token validation and, optionally, scopes in the token.

Only the AWS::Serverless::HttpApi resource type supports OAuth 2.0/JWT authorizers.

For more information, see Controlling access to HTTP APIs with JWT authorizers in the API Gateway Developer Guide. For an example, see OAuth 2.0/JWT authorizer example.

Lambda authorizer examples

IAM permission example

Amazon Cognito user pool example

API key example

Resource policy example

OAuth 2.0/JWT authorizer example

Customized response example