How do I implement IAM authentication for APIs created with Amazon API Gateway?

Last updated: 2016-08-31

I have created an API in Amazon API Gateway and would like to implement IAM authentication for access to my API. How do I do this?

Short Description

With Amazon API Gateway, you can create an API using the API Gateway console, AWS CLI, the API Gateway control service REST API, and platform-specific or language-specific SDKs. The example in this article was created with the Amazon API Gateway console as described at Build and Test an API Gateway API from an Example. This article describes how to implement IAM authentication for Amazon API Gateway APIs by using of the IAM console.


Get set up

  1. If you do not yet have an AWS account, go to Get Ready to Use Amazon API Gateway and Sign Up for AWS.
  2. Create an IAM user as described at Create an IAM User, Group or Role in Your AWS Account; this IAM user can be used in lieu of root credentials to designate IAM authentication for other IAM users.
  3. Complete the steps at Grant IAM Users Permissions to Access API Gateway Control and Execution Services to grant the IAM user the permissions required to designate IAM authentication for other IAM users.
  4. After you have granted an IAM user appropriate permissions for the API Gateway, sign in to the Amazon API Gateway console as that IAM user and follow the steps to Build and Test an API Gateway API from an Example if you have not yet created an API Gateway API.

Enable authorization for the API

  1. Select your API from the list of APIs, and choose Resources.
  2. Choose the POST method displayed at the top of the list of the API resources for the API.
  3. Select Method Request from the pane on the right. If you created your API using the Example API instructions, the Auth setting for Method Request is set to NONE by default.
  4. Select the icon displayed to the immediate right of Authorization NONE; this presents a drop-down box that you can use to change the authorization settings for the API POST method request from NONE to AWS_IAM.
  5. Select AWS_IAM, and then select the check box on the right to confirm your choice. After you change the authorization settings for the API POST method request from NONE to AWS_IAM, you must explicitly grant user access to the API with an IAM policy.
  6. Select the newly modified POST method displayed in the middle Resources pane of the API console, and then select Actions at the top of the middle pane to display a drop-down box.
  7. For Actions, choose Deploy API. This deploys the changes made to the resources, and applies the authorization settings that you updated.

Grant API authorization to IAM users with a policy

Although you can grant user access to the API at the individual IAM user level, it is recommended that you grant access to Amazon API Gateway APIs at the IAM group level.

  1. Open the AWS IAM console and select Groups.
  2. Select an existing group name or create a new group and select the name of the group to display the Group Summary page. Ensure that the Users tab is selected on the Group Summary page and select Add Users to Group to list your IAM users. Access to the API will be granted to IAM users that you add to this group.
  3. Choose one or more IAM users to add to the group, and then select Add Users. The Group Summary page will be displayed again.
  4. On the Permissions tab, choose Attach Policy.
  5. Choose the AmazonAPIGatewayInvokeFullAccess policy, and then choose Attach Policy.

Each member of this group can now access Amazon API Gateway APIs that implement AWS_IAM authorization settings. IAM users that are not members of the group can still access APIs with an Authorization setting of NONE, but they will receive the error message {"message":"Missing Authentication Token"} when attempting to make a request to an API's resource with a method that requires AWS_IAM authorization.

Verify the authorization settings

  1. In the Amazon API Gateway console, select your API.
  2. From the categories that are displayed beneath the API in the left pane, choose the Stages category.
  3. From the middle pane of the API Gateway console, select the triangle next to the top stage of your API to expand the API hierarchy of methods and options. If you created the example API, select the GET method listed under the /pets/{petId} stage at the bottom of the hierarchy.

Make a note of the Invoke URL: listed at the top of this page. This URL should look similar to the following if you created the example Amazon API Gateway API:{petId}

This url can be used to invoke the /pets/{petId} resource in the example API by opening a browser and substituting {petId} with an integer value; for example, /pets/555.

Verify that AWS_IAM authorization settings are in effect by making a SigV4 signed request (such as through the Postman application using AWS Signature Authorization type) to the URL using IAM credentials from an IAM user that is a member of the group with the attached AmazonAPIGatewayInvokeFullAccess policy. After you verify that you can connect to the URL without any errors, make another unsigned request (no IAM credentials) to the Invoke URL.