Define authorization rules

When determining the authorization mode for your REST endpoint, there are a few customizations you can do.

IAM Authorization

By default, the API will be using IAM authorization and the requests will be signed for you automatically. IAM authorization has two modes: one using an unauthenticated role, and one using an authenticated role. When the user has not signed in, the unauthenticated role is used by default. Once the user has signed in, the authenticate role is used, instead.

When you created your REST API with the Amplify CLI, you were asked if you wanted to restrict access. If you selected no, then the unauthenticated role will have access to the API. If you selected yes, you would have configured more fine grain access to your API.

API Key

If you want to configure a public REST API, you can set an API key in Amazon API Gateway. Then, you can set the API key header in the API category configuration. The API key header will be applied to all requests.

1Amplify.configure(awsconfig, {
2  API: {
3    REST: {
4      headers: async () => {
5        return { 'X-Api-Key': apiKey };
6      }
7    }
8  }
9});

Cognito User Pool Authorization

If you set up the API Gateway with a custom authorization with a Cognito User pool, your amplifyconfiguration.json should contain Cognito user pool information:

1const awsmobile = {
2  ...
3  "aws_cognito_region": "[REGION]",
4  "aws_user_pools_id": "[YOUR_USER_POOL_ID]",
5  "aws_user_pools_web_client_id": "[YOUR_USER_POOL_WEB_CLIENT_ID]",
6  ...
7}

You can use the access token from configured Cognito User Pool to authenticate against REST endpoint. The JWT token can be retrieved from the Auth category.

1import { fetchAuthSession } from 'aws-amplify/auth'
2...
3const authToken = (await fetchAuthSession()).tokens?.idToken?.toString();

Then you need to set the Authorization header in the API category configuration. The following example shows how to set the Authorization header for all requests.

1Amplify.configure(awsconfig, {
2  API: {
3    REST: {
4      headers: async () => {
5        return { Authorization: authToken };
6      }
7    }
8  }
9});

For more details on how to configure the API Gateway with the custom authorization, see this

Custom Authorization Token

If you want to use a custom authorization token, you can set the token in the API category configuration. The custom authorization token will be applied to all requests.

1Amplify.configure(awsconfig, {
2  API: {
3    REST: {
4      headers: async () => {
5        return { Authorization: customAuthToken };
6      }
7    }
8  }
9});

Note related to use Access Token or ID Token

The ID Token contains claims about the identity of the authenticated user such as name, email, and phone_number. It could have custom claims as well, for example using Amplify CLI. On the Amplify Authentication category you can retrieve the Id Token using:

1const idToken = (await fetchAuthSession()).tokens?.idToken?.toString();

The Access Token contains scopes and groups and is used to grant access to authorized resources. This is a tutorial for enabling custom scopes.. You can retrieve the Access Token using

1const accessToken = (await fetchAuthSession()).tokens?.accessToken.toString();

Setting Authorization Headers per Request

Alternatively, you can set the authorization headers per request. For example, if you want to use a custom header named Authorization for a specific REST request, you can set the following configuration:

1async function updateTodo() {
2  await del({
3    apiName: 'todo-api',
4    path: '/todo/1',
5    options: {
6      headers: {
7        Authorization: authToken
8      }
9    }
10  }).response;
11}

Customizing HTTP request headers

To use custom headers on your HTTP request, you need to add these to Amazon API Gateway first. For more info about configuring headers, please visit Amazon API Gateway Developer Guide

If you have used Amplify CLI to create your API, you can enable custom headers by following above steps:

1. Visit Amazon API Gateway console.
2. On Amazon API Gateway console, click on the path you want to configure (e.g. /{proxy+})
3. Then click the Actions dropdown menu and select Enable CORS
4. Add your custom header (e.g. my-custom-header) on the text field Access-Control-Allow-Headers, separated by commas, like: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token,my-custom-header'.
5. Click on 'Enable CORS and replace existing CORS headers' and confirm.
6. Finally, similar to step 3, click the Actions drop-down menu and then select Deploy API. Select Development on deployment stage and then Deploy. (Deployment could take a couple of minutes).