# Microsoft Dynamics CRM — CRM API: connection

> Canonical URL: https://developers.apideck.com/apis/crm/microsoft-dynamics/connection

# How to connect to Microsoft Dynamics CRM

A Microsoft Dynamics CRM connection links Apideck to **one** Dynamics 365 environment. Before you can authorise, you supply that environment's **Organisation URL**; Apideck then uses your own Microsoft work account to read and write records on your behalf.

## Prerequisites

- A **work or school account** (Microsoft Entra ID) in the tenant that hosts your Dynamics 365 environment. Personal Microsoft accounts cannot be used, because they have no Dynamics 365 environment behind them.
- A **full Dynamics 365 user licence** (for example Sales Enterprise or another Customer Engagement licence). A Team Member licence only covers the designated Team Member apps and a restricted set of actions, so it is usually not enough for a connection that reads and writes across records. See [Dynamics 365 Team Members licensing](https://learn.microsoft.com/en-us/dynamics365/get-started/team-members-license).
- A **Dynamics 365 online environment**. The connector signs in through Microsoft Entra ID and calls the online Dataverse Web API, so it connects to environments hosted by Microsoft rather than on-premises installations.
- The **Organisation URL** of the environment you want to connect. If you cannot open the admin screens below, ask your Dynamics 365 or Power Platform administrator for it.

## Step 1: Find your Organisation URL

The value looks like `https://yourorg.crm.dynamics.com`, where `yourorg` is your environment name. The segment after it depends on the data centre your environment lives in (`crm` for North America, `crm2` for South America, `crm7` for Japan, and so on), and a few data centres use a base other than `dynamics.com`. Microsoft lists them all under [Datacenter regions](https://learn.microsoft.com/en-us/power-platform/admin/new-datacenter-regions).

There are two reliable routes to it.

**Power Platform admin center (recommended)**

1. Sign in to the [Power Platform admin center](https://admin.powerplatform.microsoft.com).
2. Select **Environments** and open the environment you want to connect.
3. Copy the **Environment URL**. This is the value Vault expects, without any trailing slash.

**Power Apps**

1. Sign in to [Power Apps](https://make.powerapps.com) and select your environment in the top-right corner.
2. Select the **Settings** button in the top-right corner, then **Developer resources**.
3. Copy the **Web API endpoint** and remove the `/api/data/v9.x/` tail from it. If the host contains an extra `api.` segment (for example `https://yourorg.api.crm.dynamics.com`), remove that segment too, so that you end up with the plain environment address `https://yourorg.crm.dynamics.com`.

When you have both values available, use the **Environment URL** from the admin center: it is already in the form Vault expects.

Two things to strip before you paste:

- **Any path.** `/main.aspx`, `/api/data/v9.2/` and anything else after the host do not belong in the setting.
- **Any trailing slash.** Apideck appends `/api/data/v9.0/` to what you enter, so a trailing slash produces a doubled separator and requests fail.

## Step 2: Enter the URL and authorise

1. In Apideck Vault, select **Microsoft Dynamics CRM**.
2. Fill in **Organisation URL** with the value from step 1. The connector normalises the scheme, so pasting the address with or without `https://` both work.
3. This setting is required *before* authorisation: Vault will not start the Microsoft sign-in until it is filled in. Apideck also sends it to Microsoft as the resource the access token is issued for, which is why a typo fails at sign-in rather than later.
4. Select **Authorize**. You are taken to Microsoft's sign-in page.
5. Sign in with your work or school account and review the permission request. The permission asked for is Microsoft's **Access Dynamics 365 as organization users** (`user_impersonation`), a delegated permission: Apideck acts as you, so it can only reach the records your own Dynamics 365 user can already reach.
6. Accept the request. You are returned to Vault and the connection becomes usable.

### If an administrator has to approve first

Some tenants configure their Microsoft Entra user consent policy so that users cannot consent to applications themselves. When that is the case, sign-in ends on an approval screen instead of returning to Vault, with wording such as "Need admin approval" or "Approval required".

Most often this is a policy your own Microsoft Entra tenant controls, so the path forward runs through your administrator rather than through Apideck. The same screen can also appear when the application's publisher is not yet verified by Microsoft; in that case the fix sits with whoever provides the integration, so if your administrator reports that they cannot approve it either, raise it with the application provider.

- If the screen offers a **Request approval** button, use it: your request goes to the administrators who can grant it.
- Otherwise, ask a Global Administrator or Application Administrator to approve the application for your organisation. Ask them for an expected timeline if you are planning around it.
- Once approval is in place, return to Vault and select **Authorize** again.

Background on the policy itself is in Microsoft's [Configure how users consent to applications](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-user-consent).

## Notes

- **One connection covers one environment.** If you work with several Dynamics 365 environments (production alongside a sandbox, or separate environments per business unit), create one connection per environment, each with its own Organisation URL.
- **Long idle periods end the connection.** Apideck refreshes your access token automatically, but the underlying Microsoft refresh token expires after 90 days without use. An integration that sits idle for three months has to be authorised again. Regular use keeps it alive.
- **The connection follows the account that authorised it.** Because access is delegated, everything Apideck does is done as that user. If they leave, lose their Dynamics 365 licence, or have their security role narrowed, the connection can start returning permission errors. Reconnect with an account that holds the access you need, and consider using an account that is not tied to one individual's day-to-day role.

## Troubleshooting

**Sign-in fails, or the connection fails immediately after selecting Authorize**

The Organisation URL is almost always the cause, because Apideck uses it to request the token before any data is read. Re-check it character by character against the **Environment URL** in the Power Platform admin center, and confirm you are signing in with an account in the same tenant as that environment.

**The connection is created but requests return 404 or "not found"**

Check for a trailing slash or a leftover path in the Organisation URL. The value should end at the host, for example `https://yourorg.crm.dynamics.com`, with nothing after it.

**Sign-in ends on an approval screen**

Usually your tenant's consent policy requires administrator approval; if your administrator cannot approve it either, the application's publisher may not be verified yet, which only the application provider can fix. See [If an administrator has to approve first](#if-an-administrator-has-to-approve-first) above.

**Requests return 403, or expected records are missing**

Two usual causes, both on the Dynamics 365 side:

- A **Team Member licence**, which restricts which apps and actions the account may use. A full Dynamics 365 licence resolves it.
- A **security role** that does not grant read or write on the tables involved. Ask your Dynamics 365 administrator to review the roles assigned to the connecting user.

**Requests start returning 401 after a quiet period**

The refresh token expired after 90 days of inactivity. Open the connection in Vault and authorise again.

## Additional resources

- [Compose HTTP requests and handle errors](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/compose-http-requests-handle-errors) (how Microsoft describes the parts of your environment URL)
- [Use OAuth authentication with Microsoft Dataverse](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/authenticate-oauth)
- [Apideck Support](https://help.apideck.com/en/articles/7774658)


[API reference](https://developers.apideck.com/apis/crm/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/crm/coverage)