> For the complete documentation index, see [llms.txt](https://docs.aisuru.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisuru.com/en/advanced-features/integrations/mcp/aisuru-mcp-which-ones-and-how-to-activate/23.-microsoft-dynamics-365.md).

# 23. Microsoft Dynamics 365

By connecting **Microsoft Dynamics 365** (and any Power App built on **Microsoft Dataverse**) to your agent it can read and write contacts, leads, opportunities, support cases, orders, activities anything modelled as a Dataverse table.

## What it can do

* **Read and search records of any table** (accounts, contacts, leads, opportunities, cases, orders, products, activities, etc.)
* **Create, update and delete records** (with confirmation for deletions)
* Run powerful queries: **OData** (filter, sort, aggregate) and **FetchXML** (complex joins, sums and counts)
* Explore the schema: **tables, columns, relationships, option sets, roles and users**
* **Execute custom actions and functions** in your Dataverse environment (workflows and plugins exposed as actions)
* **Manage record links** (1:N and N:N associations)

## Examples

*"Find the 5 hottest leads from the last 30 days and give me their phone and latest note."*\
\
*"Create a new contact "Jane Doe" linked to the account "ACME Inc"."*\
\
*"How many cases were opened this month, grouped by priority?"*\
\
*"List all accounts with no open opportunity, including the primary contact's email."*

## Supported products

Everything that runs on **Microsoft Dataverse**:

* **Dynamics 365 Sales** (sales CRM)
* **Dynamics 365 Customer Service** (cases / ticketing)
* **Dynamics 365 Field Service**
* **Dynamics 365 Marketing**
* **Dynamics 365 Project Operations**
* Custom **Power Apps** built on Dataverse

{% hint style="warning" %}
**Not covered**: Dynamics 365 **Business Central** and **Finance & Operations** have separate APIs and are not reachable through this connector.
{% endhint %}

## Configuration parameters (application authentication)

The connector uses an **application identity** (App Registration in Microsoft Entra ID): a single service account with the permissions you choose, shared by all users of the agent. This is the standard pattern for enterprise CRM integrations.

Five values are required, gathered through the 6 steps below. **Estimated time: 15-20 minutes**. You need Microsoft 365 admin privileges (to create the App Registration) and Dynamics / Power Platform admin privileges (to assign permissions on the environment).

#### Step 1 — Get the Dataverse environment URL

Go to [**admin.powerplatform.microsoft.com**](https://admin.powerplatform.microsoft.com/) → left menu **"Environments"** → click the name of the Dynamics environment to connect. 

On the right card, under "Details", you'll find **"Environment URL"**: copy the full HTTPS address (e.g. `https://orgXXXXXXXX.crm4.dynamics.com` — the suffix `crm`, `crm4`, `crm12`… depends on the tenant region).

→ this is the **`DATAVERSE_ENV_URL`** value.

#### Step 2 — Get the Tenant ID

Go to [**portal.azure.com**](https://portal.azure.com/) → search **"Microsoft Entra ID"** in the top bar and open it → on the **"Overview"** page you'll find **"Tenant ID"** (a GUID like `ab12cd34-e5f6-7890-abcd-1234567890ab`). Click the copy icon.

→ this is the **`AZURE_TENANT_ID`** value.

#### Step 3 — Create the App Registration in Entra ID

Still on [portal.azure.com](https://portal.azure.com/) → **"Microsoft Entra ID"** → left menu **"App registrations"** → top bar **"+ New registration"**.

* **Name**: a recognisable name (e.g. `AIsuru Dynamics Connector`)
* **Supported account types**: choose **"Accounts in this organizational directory only"** (single tenant — the standard case)
* **Redirect URI**: leave blank (the connector does not use interactive flows)
* Click **"Register"**

The new App's page opens. From the **"Overview"** copy **"Application (client) ID".**

→ this is the **`AZURE_CLIENT_ID`** value.

#### Step 4 — Generate the Client Secret

On the same App, left menu **"Certificates & secrets"** → tab **"Client secrets"** → **"+ New client secret"**.

* **Description**: e.g. `AIsuru secret`
* **Expires**: recommended `24 months` (note the expiry date, you'll need to rotate it)
* Click **"Add"**

{% hint style="warning" %}
**Important**: right after creation the page shows two columns: **"Value"** and **"Secret ID"**. **Copy the "Value" immediately** (shown only once — if you navigate away you'll have to create a new one). DO NOT copy the "Secret ID" (that's just the technical identifier, it cannot be used to authenticate).
{% endhint %}

→ this is the **`AZURE_CLIENT_SECRET`** value (stored encrypted by the gateway).

#### Step 5 — Add the App as an Application User in Dataverse

The App Registration created in Entra ID **does not automatically have access to Dynamics data**. It must be explicitly added as an "application user" on the Dataverse environment.

Go back to [**admin.powerplatform.microsoft.com**](https://admin.powerplatform.microsoft.com/) → **"Environments"** → click the environment → **"Settings"** tab at the top → section **"Users + permissions"** → **"Application users"** → **"+ New app user"**.

* Click **"+ Add an app"** → a side panel opens → search the App by name (e.g. "AIsuru Dynamics Connector") → select → **"Add"**
* **Business Unit**: leave the default (the environment's root business unit), unless you want to scope the agent to a specific BU
* **Security roles**: click the pencil icon → select **at least one role** (see "Which security role?" below) → **"Save"**
* Click **"Create"** at the bottom

The App now appears in the environment's Application users list and is authorised to call the Dataverse API with the chosen role's permissions.

### Which security role to assign?

The role determines **what the agent can do** on the data. Choose based on the use case:

* **Read-only CRM (customer master data, sales history, opportunities — view only)**: create a custom role with **Read** permission organization-wide on `account`, `contact`, `lead`, `opportunity`, `opportunityproduct`, `salesorder`, `salesorderdetail`, `invoice`, `invoicedetail`, `quote`, `incident` (cases), `systemuser`, `businessunit`. This is the recommended setup to start in production: the agent can answer questions about data but cannot change anything
* **CRM with limited write access (the agent creates/updates leads, opportunities, activities, contacts)**: in addition to the Read above, add **Create / Append / Append To / Write** on `account`, `contact`, `lead`, `opportunity`, `task`, `phonecall`, `email`, `appointment`. **No Delete**: the agent should not remove master records
* **Dev / sandbox only**: built-in role **"System Administrator"** (full permissions). Convenient for testing, do not use in production

{% hint style="info" %}
**Tip**: when in doubt, start with the read-only profile and broaden only when new operations are needed. If a tool fails on permissions, the error message says it explicitly and you just add the missing privilege to the role.
{% endhint %}

## Recap: where to find each value

| Parameter             | Where                                                   | What                                                   |
| --------------------- | ------------------------------------------------------- | ------------------------------------------------------ |
| `DATAVERSE_ENV_URL`   | Power Platform admin center → Environment → Details     | HTTPS URL of the Dataverse environment                 |
| `AUTH_METHOD`         | (fixed)                                                 | Leave `client-credentials`                             |
| `AZURE_TENANT_ID`     | Azure portal → Microsoft Entra ID → Overview            | "Tenant ID" (GUID)                                     |
| `AZURE_CLIENT_ID`     | Azure portal → App registration → Overview              | "Application (client) ID" (GUID)                       |
| `AZURE_CLIENT_SECRET` | Azure portal → App registration → Certificates\&secrets | The **"Value"** column of the secret (NOT "Secret ID") |

### Troubleshooting (if the agent fails on the first call)

* **`AADSTS7000215: Invalid client secret`** → the secret is wrong or expired. Did you copy the "Secret ID" by mistake instead of the "Value"? Generate a new secret and copy the **Value** correctly
* **`AADSTS700016: Application not found in tenant`** → `AZURE_TENANT_ID` does not match the tenant where you created the App. Verify both
* **`Principal user (AppId=…) is missing prvReadOrganization privilege`** or **`0x80040220`** → you forgot to add the App as an Application User on the environment (Step 5), or the assigned security role is insufficient for the table the agent is querying
* **`The user does not have access to the Common Data Service environment`** → the App was added in the WRONG environment (you're in another tenant or another environment of the same tenant). Make sure `DATAVERSE_ENV_URL` points to the same environment where you did Step 5
* **Immediate `401 Unauthorized`** → `AZURE_CLIENT_ID` does not match the App Registration, or the secret has been revoked in Azure

{% hint style="danger" %}
**Security note:** all users of the agent operate with the App Registration's permissions. Assign the App the **least privilege** required in Dataverse and consider Business Unit / Team scoping if you want to restrict access to records within a single organisational area.
{% endhint %}