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.

A user pool is integrated with an API as a method authorizer. 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 back end.

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 and then choose Cognito User Pool Authorizer.

  4. To configure this authorizer:

    1. Choose a region for Cognito region.

    2. For Cognito User Pool, choose an available user pool.

    3. The Authorizer name field will be automatically populated with the chosen user pool name. However, you can customize it if you want to.

    4. The Identity token source field will be set to method.request.header.Authorization by default. However, you can customize it if you want to. Using the default, Authorization will be the name of the incoming request header to contain an API caller's identity token.

    5. Optionally, type a regular expression in the App client ID regex field to validate client IDs associated with the user pool.

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

  5. Having created the authorizer, you can, optionally, test it by supplying an identity token provisioned from the user pool.

To enable a user pool authorizer on methods

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

  2. Choose Method Request.

  3. Under Authorization Settings, choose the edit icon by the Authorization field.

  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 back end. 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 back end:

    { "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 a 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 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 Import and Export API.

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.