Control Access for Managing an API
In this section, you will learn how to write up IAM policy statements to control
who can or cannot create, deploy and update an API in API Gateway. You'll also find
the policy
statements reference, including the formats of the Action
and Resource
fields related to the
API managing service.
Control Who Can Create and Manage an API Gateway API with IAM Policies
To control who can or cannot create, deploy and update your API using the API managing service of API Gateway, create an IAM policy document with required permissions as shown in the following policy template:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "
Permission
", "Action": [ "apigateway:HTTP_VERB
" ], "Resource": [ "arn:aws:apigateway:region
::resource1-path
", "arn:aws:apigateway:region
::resource2-path
", ... ] } ] }
Here,
can
be Permission
Allow
or Deny
to
grant or revoke, respectively, the access rights as stipulated by the policy
statement. For more information, see AWS IAM
permissions.
can be any of
the
API Gateway-supported HTTP verbs. HTTP_VERB
*
can be used
to denote any of the HTTP verbs.
Resource
contains a list of ARNs of the affected API
entities, including RestApi,
Resource, Method, Integration, DocumentationPart,
Model, Authorizer, UsagePlan, etc. For more
information, see Resource Format of Permissions for Managing API in API Gateway.
By combining different policy statements, you can customize the access permissions for individual users, groups or roles to access selected API entities and to perform specified actions against those entities. For example, you can include the following statement in the IAM policy to grant your documentation team the permissions to create, publish, update and delete the documentation parts of a specified API as well as to view the API entities.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "apigateway:GET" ], "Resource": [ "arn:aws:apigateway:
region
::/restapis/api-id
/*" ] }, { "Effect": "Allow", "Action": [ "apigateway:POST", "apigateway:PATCH", "apigateway:DELETE" ], "Resource": [ "arn:aws:apigateway:region
::/restapis/api-id
/documentation/*" ] } ] }
For your API core development team who is responsible for all operations, you can include the following statement in the IAM policy to grant the team much broader access permissions.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "apigateway:*" ], "Resource": [ "arn:aws:apigateway:*::/*" ] } ] }
Statement Reference of IAM Policies for Managing API in API Gateway
The following information describes the Action
and
Resource
element format used in an IAM policy statement to grant
or revoke permissions for managing API Gateway API entities.
Action Format of Permissions for Managing API in API Gateway
The API-managing Action
expression has the following general
format:
apigateway:
action
where action
is one of the following API Gateway
actions:
-
*, which represents all of the following actions.
-
GET, which is used to get information about resources.
-
POST, which is primarily used to create child resources.
-
PUT, which is primarily used to update resources (and, although not recommended, can be used to create child resources).
-
DELETE, which is used to delete resources.
-
PATCH, which can be used to update resources.
-
HEAD, which is the same as GET but does not return the resource representation. HEAD is used primarily in testing scenarios.
-
OPTIONS, which can be used by callers to get information about available communication options for the target service.
Some examples of the Action
expression include:
-
apigateway:*
for all API Gateway actions. -
apigateway:GET
for just the GET action in API Gateway.
Resource Format of Permissions for Managing API in API Gateway
The API-managing Resource
expression has the following general
format:
arn:aws:apigateway:
region
::resource-path-specifier
where region
is a target AWS region (such as
us-east-1
or *
for all
supported AWS regions), and resource-path-specifier
is the path to the target resources.
Some example resource expressions include:
-
arn:aws:apigateway:
for all resources, methods, models, and stages in the AWS region ofregion
::/restapis/*region
. -
arn:aws:apigateway:
for all resources, methods, models, and stages in the API with the identifier ofregion
::/restapis/api-id
/*api-id
in the AWS region ofregion
. -
arn:aws:apigateway:
for all resources and methods in the resource with the identifierregion
::/restapis/api-id
/resources/resource-id
/*resource-id
, which is in the API with the identifier ofapi-id
in the AWS region ofregion
. -
arn:aws:apigateway:
for all of the methods in the resource with the identifierregion
::/restapis/api-id
/resources/resource-id
/methods/*resource-id
, which is in the API with the identifier ofapi-id
in the AWS region ofregion
. -
arn:aws:apigateway:
for just the GET method in the resource with the identifierregion
::/restapis/api-id
/resources/resource-id
/methods/GETresource-id
, which is in the API with the identifier ofapi-id
in the AWS region ofregion
. -
arn:aws:apigateway:
for all of the models in the API with the identifier ofregion
::/restapis/api-id
/models/*api-id
in the AWS region ofregion
. -
arn:aws:apigateway:
for the model with the name ofregion
::/restapis/api-id
/models/model-name
model-name
, which is in the API with the identifier ofapi-id
in the AWS region ofregion
. -
arn:aws:apigateway:
for all of the stages in the API with the identifier ofregion
::/restapis/api-id
/stages/*api-id
in the AWS region ofregion
. -
arn:aws:apigateway:
for just the stage with the name ofregion
::/restapis/api-id
/stages/stage-name
stage-name
in the API with the identifier ofapi-id
in the AWS region ofregion
.