Menu
Amazon API Gateway
Developer Guide

Control Access to API Gateway with IAM Permissions

You control access to Amazon API Gateway with IAM permissions by controlling access to the following two API Gateway component processes:

  • To create, deploy, and manage an API in API Gateway, you must grant the API developer permissions to perform the required actions supported by the API management component of API Gateway.

  • To call a deployed API or to refresh the API caching, you must grant the API caller permissions to perform required IAM actions supported by the API execution component of API Gateway.

The access control for the two processes involves different permissions models, explained next.

API Gateway Permissions Model for Creating and Managing an API

To allow an API developer to create and manage an API in API Gateway, you must create IAM permissions policies that allow a specified API developer to create, update, deploy, view, or delete required API entities. You attach the permissions policy to an IAM user representing the developer, to an IAM group containing the user, or to an IAM role assumed by the user.

In this IAM policy document, the IAM Resource element contains a list of API Gateway API entities, including API Gateway resources and API Gateway link-relations. The IAM Action element contains the required API Gateway API-managing actions. These actions are declared in the apigateway:HTTP_VERB format, where apigateway designates the underlying API management component of API Gateway, and HTTP_VERB represents HTTP verbs supported by API Gateway.

For more information on how to use this permissions model, see Control Access for Managing an API.

API Gateway Permissions Model for Invoking an API

To allow an API caller to invoke the API or refresh its caching, you must create IAM policies that permit a specified API caller to invoke the API method for which the IAM user authentication is enabled. The API developer sets the method's authorizationType property to AWS_IAM to require that the caller submit the IAM user's access keys to be authenticated. Then, you attach the policy to an IAM user representing the API caller, to an IAM group containing the user, or to an IAM role assumed by the user.

In this IAM permissions policy statement, the IAM Resource element contains a list of deployed API methods identified by given HTTP verbs and API Gateway resource paths. The IAM Action element contains the required API Gateway API executing actions. These actions include execute-api:Invoke or execute-api:InvalidateCache, where execute-api designates the underlying API execution component of API Gateway.

For more information on how to use this permissions model, see Control Access for Invoking an API.

When an API is integrated with an AWS service (for example, AWS Lambda) in the back end, API Gateway must also have permissions to access integrated AWS resources (for example, invoking a Lambda function) on behalf of the API caller. To grant these permissions, create an IAM role of the Amazon API Gateway type. This role contains the following IAM trust policy that declares API Gateway as a trusted entity that is permitted to assume the role:

Copy
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

You must also attach to this role IAM permissions policies for calling integrated AWS services. For example, if the backend is Lambda, the IAM permissions policy must include the following permissions policy statement:

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" } ] }

Note that Lambda supports resource-based access policy, which combines both trust and permissions policies. When integrating an API with a Lambda function using the API Gateway console, you are not asked to set this IAM role explicitly, because the console sets the resource-based permissions on the Lambda function for you, with your consent.

Note

To enact access control to an AWS service, you can use either the caller-based permissions model, where a permissions policy is directly attached to the caller's IAM user or group, or the role-based permission model, where a permissions policy is attached to an IAM role that API Gateway can assume. The permissions policies may differ in the two models. For example, the caller-based policy blocks the access while the role-based policy allows it. You can take advantage of this to require that an IAM user access an AWS service through an API Gateway API only.