Control access for invoking an API
In this section, you learn about the permissions model for controlling access to your API using IAM
permissions. We show a template IAM policy statement and the policy statement reference. The policy statement
reference includes the formats of Action
and Resource
fields related to the API execution service. Use these references to create your IAM policy
statement. When you create your IAM policy statement, you might need to consider the how API Gateway resource policies
affect the authorization workflow. For more information, see How API Gateway resource policies affect
authorization workflow.
For private APIs, you should use a combination of an API Gateway resource policy and a VPC endpoint policy. For more information, see the following topics:
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.
{ "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,
is to be replaced by
Permission
Allow
or Deny
depending on whether you want to grant or revoke the included permissions.
is to be
replaced by the operations supported by the API execution service.
Execution-operation
stands for a HTTP
verb supported by the specified resources. METHOD_HTTP_VERB
is the placeholder for the
URL path of a deployed API Resource-path
Resource
instance supporting the said
. For more
information, see Statement reference of IAM
policies for executing API in API Gateway. METHOD_HTTP_VERB
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 publicly accessible.
For example, to grant a user permission to view a list of pets exposed by a specified API, but to deny the user permission to add a pet to the list, you could include the following statement in the IAM policy:
{ "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
" ] } ] }
To grant a user permission to view a specific pet exposed by an API that is
configured as GET /pets/
, you could
include the following statement in the IAM policy:{petId}
{ "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
/a1b2
" ] } ] }
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:
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:
arn:aws:execute-api:
region
:account-id:api-id
/stage-name
/HTTP-VERB
/resource-path-specifier
where:
-
region
is the Amazon region (such asus-east-1
or*
for all Amazon regions) that corresponds to the deployed API for the method. -
account-id
is the 12-digit Amazon account Id of the REST API owner. -
api-id
is the identifier API Gateway has assigned to the API for the method. -
stage-name
is the name of the stage associated with the method. -
HTTP-VERB
is the HTTP verb for the method. It can be one of the following: GET, POST, PUT, DELETE, PATCH. -
resource-path-specifier
is the path to the desired method.
Note
If you specify a wildcard (*
), the Resource
expression applies the wildcard to the rest of the expression.
Some example resource expressions include:
-
arn:aws:execute-api:*:*:*
for any resource path in any stage, for any API in any Amazon region. -
arn:aws:execute-api:us-east-1:*:*
for any resource path in any stage, for any API in the Amazon region ofus-east-1
. -
arn:aws:execute-api:us-east-1:*:
for any resource path in any stage, for the API with the identifier ofapi-id
/*api-id
in the Amazon region of us-east-1. -
arn:aws:execute-api:us-east-1:*:
for any resource path in the stage ofapi-id
/test
/*test
, for the API with the identifier ofapi-id
in the Amazon region of us-east-1.
To learn more, see API Gateway Amazon Resource Name (ARN) reference.