Amazon API Gateway
Developer Guide

Use Amazon Cognito User Pools

In addition to using IAM roles and policies or custom authorizers, you can also use a user pool in Amazon Cognito to control who can access your API in API Gateway. A user pool serves as your own identity provider to maintain a user directory. It supports user registration and sign-in, as well as provisioning identity tokens for signed-in users.


To get the permissions of an IAM role using Amazon Cognito credentials, use Amazon Cognito Federated Identities to get temporary credentials and set the authorization type to AWS_IAM on your API.

A user pool is integrated with an API as a method authorizer that is applicable for any method. When calling the methods with such an authorizer enabled, an API client includes in the request headers the user's identity token provisioned from the user pool. API Gateway then validates the token to ensure it belongs to the configured user pool and authenticates the caller before passing the request to the backend.

To integrate an API with the Amazon Cognito identity provider, you, as an API developer, create and own a user pool, create an API Gateway authorizer connected to the user pool, and enable the authorizer on selected API methods. You must also distribute to your API client developers the user pool ID, a client ID, and possibly the associated client secret that are provisioned from the user pool. The client will need this information to register users with the user pool, to provide the sign-in functionality, and to have the user's identity token provisioned from the user pool.

In this section, you will learn how to create a user pool, how to integrate an API Gateway API with the user pool, and how to invoke an API integrated with the user pool.

Create a User Pool

Before integrating your API with a user pool, you must create the user pool in Amazon Cognito. For instructions on how to create a user pool, see Setting up User Pools in the Amazon Cognito Developer Guide.


Make a note of the user pool ID, client ID and the client secret, if selected. The client will need to provide them to Amazon Cognito for the user to register with the user pool, to sign in to the user pool, and to get an identity token to be included in requests to call API methods configured with the user pool. Also, you will need to specify the user pool name when you configure the user pool as an authorizer in API Gateway, as described next.

Integrate an API with a User Pool

To integrate your API with a user pool, you must create in API Gateway a user pool authorizer connected to the user pool. The following procedure walks you through the steps to do this using the API Gateway console.

To create a user pool authorizer using the API Gateway console

  1. Create a new API or select an existing API in API Gateway.

  2. From the main navigation pane, choose Authorizers under the specified API.

  3. Under Authorizers, choose Create New Authorizer and then do the following to configure the new Amazon Cognito user pool authorizer:

    1. Type an authorizer name in the Name.

    2. Select the Cognito option.

    3. Choose a region under Cognito User Pool.

    4. Select an available user pool. You must have created a user pool for the selected region in Amazon Cognito for it to show up in the drop-down list.

    5. For Token source type Authorization as the header name to pass the identity token returned by Amazon Cognito when a user logs in successfully.

    6. Optionally, type a regular expression in the Token validation field to validate the token before authorizing with Amazon Cognito.

    7. Choose Create to finish integrating the user pool with the API.

  4. Having created the authorizer, you can, optionally, test invoking it by supplying an identity token provisioned from the user pool. You can obtain this identity token by calling Amazon Cognito Identity SDK to perform user sign-in. Make sure to use the returned identity token, not the access token.

To enable a user pool authorizer on methods

  1. Choose (or create) a method of your API.

  2. Choose Method Request.

  3. Under Settings, choose the pencil icon next to Authorization.

  4. Choose one of the available Amazon Cognito user pool authorizers from the drop-down list.

  5. Choose the check-mark icon to save the settings.

  6. Repeat these steps for other methods of your choosing.

  7. If needed, choose Integration Request to add $['property-name'] or $ expressions in a body-mapping template to pass the specified identity claims property from the user pool to the backend. For simple property names, such as sub or custom-sub, the two notations are identical. For complex property names, such as custom:role, the dot notation may not be used. For example, the following mapping expressions pass the claim's standard fields of sub and email to the backend:

    { "context" : { "sub" : "$", "email" : "$" } }

    If you have declared a custom claim field when configuring a user pool, you can follow the same pattern to access the custom fields. The following example gets a custom role field of a claim:

    { "context" : { "role" : "$" } }

    If the custom claim field is declared as custom:role, use the following example to get the claim's property:

    { "context" : { "role" : "$['custom:role']" } }

Instead of using the API Gateway console, you can also enable an Amazon Cognito user pool on a method by configuring the settings in a Swagger definition file and import the API definition into API Gateway.

To import a user pool authorizer with a Swagger definition file

  1. Create (or export) a Swagger definition file for your API.

  2. Add the user pool settings to the securityDefinitions:

    "securityDefinitions": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } }
  3. Enable the Amazon Cognito user pool (MyUserPool) as an authorizer for a method, as shown in the following GET method on the root resource.

    "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": [] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... }
  4. If needed, you can set other API configuration using appropriate Swagger definitions or extensions. For more information, see API Gateway Extensions to Swagger.

Call an API Integrated with a User Pool

To call a method with a user pool authorizer configured, the client must do the following:

  • Enable the user to sign up with the user pool.

  • Enable the user to sign in to the user pool.

  • Obtain an identity token of the signed-in user from the user pool.

  • Include the identity token in the Authorization header (or another header you specified when creating the authorizer).

You can use one of the AWS SDKs to perform these tasks. For example:

The following procedure outlines the steps to perform these tasks. For more information, see the blog posts on Using Android SDK with Amazon Cognito User Pools and Using Amazon Cognito User Pool for iOS.

To call an API integrated with a user pool

  1. Sign up a first-time user to a specified user pool.

  2. Sign in a user to the user pool.

  3. Get the user's identity token.

  4. Call API methods configured with a user pool authorizer, supplying the unexpired token in the Authorization header or another header of your choosing.

  5. When the token expires, repeat Step 2-4. Identity tokens provisioned by Amazon Cognito expire within an hour.

For code examples, see an Android Java sample and an iOS Objective-C sample.