Menu
Amazon API Gateway
Developer Guide

Control Access for Invoking an API

In this section you will learn how to write up IAM policy statements to control who can or cannot call a deployed API in API Gateway. Here, you will also find the policy statement reference, including the formats of Action and Resource fields related to the API execution service.

Control Who Can Call an API Gateway API Method with IAM Policies

To control who can or cannot call a deployed API with IAM permissions, create an IAM policy document with required permissions. A template for such a policy document is shown as follows.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Permission", "Action": [ "execute-api:Execution-operation" ], "Resource": [ "arn:aws:execute-api:region:account-id:api-id/stage/METHOD_HTTP_VERB/Resource-path" ] } ] }

Here, Permission is to be replaced by Allow or Deny depending on whether you want to grant or revoke the included permissions. Execution-operation is to be replaced by the operations supported by the API execution service. METHOD_HTTP_VERB stands for a HTTP verb supported by the specified resources. Resource-path is the placeholder for the URL path of a deployed API Resource instance supporting the said METHOD_HTTP-VERB. For more information, see Statement Reference of IAM Policies for Executing API in API Gateway.

Note

For IAM policies to be effective, you must have enabled IAM authentication on API methods by setting AWS_IAM for the methods' authorizationType property. Failing to do so will make these API methods effectively public accessible.

When AWS identity and access management is enabled on a specific resource, IAM users from different AWS accounts cannot access that resource unless the caller is allowed to assume the resource owner’s role, because API Gateway does not currently support cross-account authentication.

For example, to grant a user the permission to view a list of pets exposed by a specified API, but to deny the user the permission to add a pet to the list, you could create the following policy statement:

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/pets" ] }, { "Effect": "Deny", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:account-id:api-id/*/POST/pets" ] } ] }

For a developer team testing APIs, you can create the following policy statement to allow the team to call any method on any resource of any API by any developer in the test stage.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke", "execute-api:InvalidateCache" ], "Resource": [ "arn:aws:execute-api:*:*:*/test/*" ] } ] }

Statement Reference of IAM Policies for Executing API in API Gateway

The following information describes the Action and Resource format of IAM policy statements of access permissions for executing an API.

Action Format of Permissions for Executing API in API Gateway

The API-executing Action expression has the following general format:

Copy
execute-api:action

where action is an available API-executing action:

  • *, which represents all of the following actions.

  • Invoke, used to invoke an API upon a client request.

  • InvalidateCache, used to invalidate API cache upon a client request.

Resource Format of Permissions for Executing API in API Gateway

The API-executing Resource expression has the following general format:

Copy
arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier

where:

  • region is the AWS region (such as us-east-1 or * for all AWS regions) that corresponds to the deployed API for the method.

  • account-id is the 12-digit AWS account Id of the REST API owner.

  • api-id is the identifier API Gateway has assigned to the API for the method. (* can be used for all APIs, regardless of the API's identifier.)

  • stage-name is the name of the stage associated with the method (* can be used for all stages, regardless of the stage's name.)

  • HTTP-VERB is the HTTP verb for the method. It can be one of the following: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.

  • resource-path-specifier is the path to the desired method. (* can be used for all paths).

Some example resource expressions include:

  • arn:aws:execute-api:*:*:* for any resource path in any stage, for any API in any AWS region. (This is equivalent to *).

  • arn:aws:execute-api:us-east-1:*:* for any resource path in any stage, for any API in the AWS region of us-east-1.

  • arn:aws:execute-api:us-east-1:*:api-id/* for any resource path in any stage, for the API with the identifier of api-id in the AWS region of us-east-1.

  • arn:aws:execute-api:us-east-1:*:api-id/test/* for resource path in the stage of test, for the API with the identifier of api-id in the AWS region of us-east-1.

  • arn:aws:execute-api:us-east-1:*:api-id/test/*/mydemoresource/* for any resource path along the path of mydemoresource, for any HTTP method in the stage of test, for the API with the identifier of api-id in the AWS region of us-east-1.

  • arn:aws:execute-api:us-east-1:*:api-id/test/GET/mydemoresource/* for GET methods under any resource path along the path of mydemoresource, in the stage of test, for the API with the identifier of api-id in the AWS region of us-east-1.