> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.

# Initial Microsoft Dynamics 365 configuration

Before your Ada team can enable the Microsoft Dynamics 365 integration, your Microsoft Azure and Dynamics 365 administrator must complete the following steps. When they are finished, share the collected values with your Ada representative.

The integration authenticates to Dynamics 365 as a service, using the OAuth client credentials flow. There is no signed-in user, so setup has two parts:

1. **In Microsoft Entra ID:** register an application and generate a client secret.
2. **In Dynamics 365:** create an Application User for that registration and assign it a security role.

Both parts are required. A registration without a matching Application User authenticates successfully, but Dynamics 365 rejects every data request it makes.

## Prerequisites

Confirm you have the following access before you start:

* A Microsoft Dynamics 365 Customer Service environment.
* Permission to create app registrations in Microsoft Entra ID.
* System Administrator access to the Dynamics 365 environment, or access to the Power Platform admin center.

## Step 1: Register an application in Microsoft Entra ID

The app registration gives the integration its own identity, separate from any user account.

**To register the application:**

1. In the [Azure portal](https://portal.azure.com), open **Microsoft Entra ID**.
2. Select **App registrations**, then click **New registration**.
3. Enter a name that identifies the integration, for example `Ada Ticketing Integration`.
4. Under **Supported account types**, select **Accounts in this organizational directory only (Single tenant)**.
5. Leave **Redirect URI** blank. The client credentials flow does not use one.
6. Click **Register**.
7. On the app's **Overview** page, record the **Application (client) ID** and the **Directory (tenant) ID**.

## Step 2: Create a client secret

The client secret is the password the integration uses to request access tokens.

**To create the client secret:**

1. In the same app registration, select **Certificates & secrets**.
2. Under **Client secrets**, click **New client secret**.
3. Enter a description and choose an expiry period.
4. Click **Add**.
5. Copy the secret's **Value** immediately and store it securely.

> **Warning**
>
> The secret **Value** is shown only once, when it is created. If you navigate away without copying it, delete the secret and create a new one. Do not copy the **Secret ID**, which is a different value and does not authenticate.

> **Note**
>
> When the secret expires, ticket creation stops working and returns an authentication error. Rotate the secret before its expiry date and send the new value to your Ada team.

## Step 3: Create an Application User in Dynamics 365

The Application User links the app registration to a Dynamics 365 identity that owns the Contacts and Cases the integration creates.

**To create the Application User:**

1. In the [Power Platform admin center](https://admin.powerplatform.microsoft.com), select **Environments**, then select your Dynamics 365 environment.
2. Click **Settings**, expand **Users + permissions**, and select **Application users**.
3. Click **New app user**.
4. Click **Add an app**, select the app registration you created in Step 1, and click **Add**.
5. Select a **Business unit**. The root business unit is normally correct.
6. Under **Security roles**, click the edit icon and assign a role that meets the requirements in Step 4.
7. Click **Create**.

## Step 4: Confirm the security role privileges

The security role determines which records the integration can read and create. The assigned role must grant the following privileges:

| Entity                                                | Privileges required | Used for                                                            |
| ----------------------------------------------------- | ------------------- | ------------------------------------------------------------------- |
| Contact                                               | Read, Create, Write | Finding an existing Contact, or creating one when there is no match |
| Case (Incident)                                       | Read, Create, Write | Creating the Case                                                   |
| Entity and Attribute metadata (**Customization** tab) | Read                | Reading Case field types. Required only if you use custom fields.   |

Set the access level to at least **Organization** for Contact and Case, so the integration can match Contacts created by other users.

> **Note**
>
> If the metadata read privilege is missing, Cases are still created, but every custom field is dropped from them.

You can assign an existing role that already grants these privileges, or create a dedicated role for the integration. A dedicated role is recommended, because it keeps the integration's access explicit and easy to audit.

## Step 5: Find your Organization URL

The Organization URL tells the integration which Dynamics 365 environment to connect to.

**To find the Organization URL:**

1. In the Power Platform admin center, select **Environments**, then select your environment.
2. Copy the **Environment URL**.

The URL looks like `https://yourorg.crm.dynamics.com`. The `crm` part varies between environments (for example `crm3`, `crm4`, or `crm11`), so use the exact value shown.

## Step 6: Verify the credentials

Confirm the credentials work before you send them to your Ada team. Replace the placeholder values and run the following request to get an access token:

```bash
curl --location 'https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=<CLIENT_ID>' \
  --data-urlencode 'client_secret=<CLIENT_SECRET>' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=<ORG_URL>/.default'
```

A successful response contains an `access_token`. Use it to confirm the Application User can read Contacts:

```bash
curl --location '<ORG_URL>/api/data/v9.1/contacts?$top=1' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Accept: application/json'
```

Use the responses to identify any problem:

* A `200` response to the second request means the app registration and the Application User are both configured correctly.
* A `401` response to the first request means the tenant ID, client ID, or client secret is wrong.
* A `403` response to the second request means the token is valid, but the Application User is missing or has no suitable role. Recheck Steps 3 and 4.

## Step 7: Share the values with your Ada team

Your Ada team uses these values to connect the integration to your AI Agent. Provide them through a secure channel:

| Value            | Where it comes from | Example                                     |
| ---------------- | ------------------- | ------------------------------------------- |
| Organization URL | Step 5              | `https://yourorg.crm.dynamics.com`          |
| Tenant ID        | Step 1              | `11111111-1111-1111-1111-111111111111`      |
| Client ID        | Step 1              | `22222222-2222-2222-2222-222222222222`      |
| Client secret    | Step 2              | The secret **Value**, not the **Secret ID** |

There is no scope value to provide. The integration derives it from the Organization URL.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).