# Connect an API that uses Amazon Cognito

If your API verifies access tokens issued by an Amazon Cognito user pool, Faustine signs in as an app client of that pool, with the client credentials grant. You create the app client in Cognito and enter its values in Faustine.

## Before you begin

- The user pool has a domain. The token endpoint is served from it.
- The user pool has a resource server for your API with at least one custom scope. Cognito issues client credentials tokens only for resource server scopes.

## Create the app client in Cognito

In the user pool, create an app client for Faustine that has a client secret and allows the client credentials grant, and allow it the custom scopes of your API's resource server. For the screens, see [Scopes, M2M, and resource servers](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html) and [The token endpoint](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html) in the Amazon Cognito documentation.

Note four values: the user pool's domain, the scopes, and the app client's ID and secret.

## Set the token endpoint on the API

1. In the portal, go to [**APIs**](https://auth.faustine.ai/go?to=%2Fintegrations%2Fapis) and select your API.
2. Select the **Authentication** tab, then **Edit**.
3. In **Sign-in method**, select **OAuth client**.
4. In **Token provider**, select **Amazon Cognito**. **Client secret sent** changes to **HTTP Basic**.
5. In **User pool domain**, enter the pool's domain, such as `acme.auth.us-east-1.amazoncognito.com`.
6. In **Scopes**, enter the scopes to request, separated by spaces. Each one is written `<RESOURCE_SERVER_ID>/<SCOPE>`, such as `nimbus-api/read nimbus-api/write`.
7. Leave **Audience** empty.
8. Select **Save changes**.

The token URL appears under **User pool domain**:

```text
https://<USER_POOL_DOMAIN>/oauth2/token
```

A custom domain works in **User pool domain** too. The next time you open the form, it shows the provider as **Custom** with the same token URL.

## Add the client to a connection

1. Select the **Connections** tab, then **New connection**, or select an existing connection.
2. In **Credentials**, enter the **Client ID** and **Client secret**.
3. In the **Test** step, select a read operation and select **Test connection**.

**Reached the endpoint** with a `2xx` status confirms that Cognito issued a token and your API accepted it.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `Identity provider refused the client credentials`, with `invalid_client` | The client ID or secret is wrong, or the app client has no secret. | Correct the values in the connection. Use an app client that has a secret. |
| `Identity provider refused the client credentials`, with `invalid_scope` | A scope is not written as `<RESOURCE_SERVER_ID>/<SCOPE>`, or the app client is not allowed it. | Correct **Scopes**, or allow the scope for the app client. |
| `Identity provider refused the client credentials`, with `unauthorized_client` | The app client does not allow the client credentials grant. | Allow the grant for the app client. |

## Next steps

- [Connect with an OAuth client](https://docs.faustine.ai/apis/connect-with-an-oauth-client/): every field of the strategy and how the token is renewed.
- [Add a connection](https://docs.faustine.ai/apis/add-a-connection/): the full wizard.
- [Authentication](https://docs.faustine.ai/apis/authentication/): the other strategies.