Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Control access to an API with IAM permissions

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

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 a user, role, or group.

To provide access, add permissions to your users, groups, or roles:

For more information on how to use this permissions model, see API Gateway identity-based policies.

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 user authentication is enabled. The API developer sets the method's authorizationType property to AWS_IAM to require that the caller submit the user's credentials to be authenticated. Then, you attach the policy to a user, role, or group.

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 Amazon service (for example, Amazon Lambda) in the back end, API Gateway must also have permissions to access integrated Amazon resources (for example, invoking a Lambda function) on behalf of the API caller. To grant these permissions, create an IAM role of the Amazon service for API Gateway type. When you create this role in the IAM Management console, this resulting role contains the following IAM trust policy that declares API Gateway as a trusted entity permitted to assume the role:

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

If you create the IAM role by calling the create-role command of CLI or a corresponding SDK method, you must supply the above trust policy as the input parameter of assume-role-policy-document. Do not attempt to create such a policy directly in the IAM Management console or calling Amazon CLI create-policy command or a corresponding SDK method.

For API Gateway to call the integrated Amazon service, you must also attach to this role appropriate IAM permissions policies for calling integrated Amazon services. For example, to call a Lambda function, you must include the following IAM permissions policy in the IAM role:

{
    "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.