# Connect an API that uses Microsoft Entra ID

If your API verifies tokens issued by Microsoft Entra ID, Faustine signs in as an application of its own, with the client credentials grant. You register that application in your directory and enter its values in Faustine.

## Before you begin

- Your API is registered in Entra ID and exposes an application ID URI, such as `api://<APP_ID>`.
- You can register applications and grant admin consent in the directory.

## Register a client in Entra ID

In Entra ID, create the following. For the screens, see [Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) and [the client credentials flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow) in the Microsoft documentation.

1. An app registration for Faustine.
2. A client secret for it. Copy the secret's value when it is created.
3. Application permissions (app roles) on your API, granted to the new application with admin consent. The client credentials grant has no user, so delegated permissions do not apply.

Note three values: the directory ID (the value for **Tenant ID**), the application (client) ID and the client 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 **Microsoft Entra ID**.
5. In **Tenant ID**, enter the directory's GUID or a verified domain, such as `contoso.onmicrosoft.com`.
6. In **Scopes**, enter the `.default` scope of your API: `api://<APP_ID>/.default`.
7. Leave **Audience** empty and **Client secret sent** on **In the body**.
8. Select **Save changes**.

The token URL appears under **Tenant ID**:

```text
https://login.microsoftonline.com/<TENANT>/oauth2/v2.0/token
```

With the client credentials grant, Entra ID accepts only the `.default` scope of a resource. The token carries the application permissions you granted.

## Add the client to a connection

| Value from Entra ID | Field in the connection |
| --- | --- |
| Application (client) ID | **Client ID** |
| Client secret value | **Client secret** |

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 Entra ID issued a token and your API accepted it.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `Identity provider refused the client credentials`, with `invalid_client` | The client secret is wrong or expired, or the secret's ID was entered instead of its value. | Create a new secret and enter its value in the connection. |
| `Identity provider refused the client credentials`, with `invalid_scope` | **Scopes** is not the `.default` scope of a resource. | Enter `api://<APP_ID>/.default`. |
| The test reaches the API and it answers `401` or `403` | The token has no `roles` claim your API accepts. | Grant the application permission with admin consent. |

## 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/): token exchange, when your API swaps the Entra ID token for its own.