Apideck CLI: Query 200+ SaaS APIs from your terminal. No SDK needed. Read more

Apideck Documentation Page

Microsoft Dynamics CRM – Configuration Guide

Service ID: microsoft-dynamics

Dynamics CRM is a leading customer resource management and enterprise resource planning software.

How to register an OAuth app for Microsoft Dynamics CRM

Microsoft Dynamics 365 authenticates through Microsoft Entra ID (the identity platform previously called Azure Active Directory), and its data lives in Microsoft Dataverse, which this connector reads and writes through the Dataverse Web API.

This guide is for the application owner. You register one multitenant Entra app, configure its Client ID and Client Secret in the Apideck Dashboard, and each consumer then authorises that app against their own Dynamics 365 environment. Publisher verification (step 6) requires your organisation to be enrolled in the Microsoft AI Cloud Partner Program.

Before you start, you'll need: a Microsoft work or school account in your own Entra tenant, with permission to register applications in that tenant. Register the app with a work or school account rather than a personal Microsoft account: a personal account cannot be used for the publisher verification in step 6.

1. Register your app in Microsoft Entra ID

  1. Sign in to the Microsoft Entra admin centre.
  2. If your account has access to more than one tenant, switch to the tenant that should own this app before you continue.
  3. Go to Identity > Applications > App registrations and select New registration. Microsoft's Register an application quickstart walks through the same screens with current screenshots.
  4. Complete the registration form:
    • Name: the name consumers and their administrators see on the Microsoft consent screen. Use your company or product name.
    • Supported account types: select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant). Multitenant is what makes the app usable by organisations outside your own tenant. Do not pick an option that also includes personal Microsoft accounts: Dynamics 365 environments only exist in work or school tenants, so a personal account has nothing to connect and the extra option only adds a confusing sign-in choice.
    • Redirect URI: set the platform to Web and enter the value in step 2, exactly.
  5. Select Register. Entra assigns the app an Application (client) ID, which you will copy in step 5.

2. Redirect URI

Apideck uses one callback address for every connector:

https://unify.apideck.com/vault/callback

If you did not set it during registration, add it under Authentication > Platform configurations > Web > Redirect URIs. Microsoft matches redirect URIs exactly (see Redirect URI restrictions), so a trailing slash, http instead of https, or any address of your own will fail the authorisation step. This is the only redirect URI the app needs.

3. Basic information and publisher domain

Open Branding & properties and complete the app's logo, home page URL, and terms of service and privacy statement links. Two reasons this is worth doing properly:

  • Consumers and their Microsoft administrators see this branding on the consent screen at the exact moment they decide whether to trust your app with their CRM data.
  • Setting a publisher domain is a prerequisite for publisher verification in step 6. It cannot be an onmicrosoft.com domain; use a DNS-verified custom domain on your tenant.

4. API permission: Dynamics CRM user_impersonation

Go to API permissions > Add a permission > Dynamics CRM > Delegated permissions, select user_impersonation (displayed as Access Dynamics 365 as organization users), and select Add permissions.

That one delegated permission is the entire permission set this connector needs. At authorisation time Apideck requests it together with the standard sign-in scope:

openid
https://admin.services.crm.dynamics.com/user_impersonation

Three points worth getting right the first time:

  • Delegated, not application. The connector calls Dataverse as the signed-in user, so there is no app-only (application) permission to add and no Dataverse application user to create in the consumer's environment. If you have integrated with Dynamics 365 before using a service principal, this is deliberately the simpler of the two models.
  • Access follows the authorising user. Every call a connection makes is made with the privileges of the user who authorised it, as granted by their Dynamics 365 security roles. Records that user cannot see or edit in Dynamics are equally invisible through the API.
  • Whether an administrator must approve the permission is decided by the consumer's tenant, through its Microsoft Entra user consent policy (configure how users consent to applications). Some tenants let any licensed user consent for themselves; others route every new application to an administrator. Plan for both, and see step 8 for the handoff.

5. Client ID and client secret

Client ID: on the app's Overview page, copy the Application (client) ID. That is the value Apideck calls the Client ID.

Client secret: go to Certificates & secrets > Client secrets > New client secret, add a description and choose an expiry. Microsoft's Add and manage application credentials covers the current screens.

Then the single most common mistake on this connector:

Copy the secret's Value, not its Secret ID. The Value is shown only once, on the page where you created it, and cannot be retrieved afterwards. The Secret ID next to it is an identifier, not a credential, and pasting it as the Client Secret produces an authorisation failure that looks like a scope or tenant problem.

Client secrets always expire. When one does, every connection using this app stops working until you paste a new secret into the Apideck Dashboard, so note the expiry date somewhere you will actually see it and rotate ahead of it: create the new secret first, update the Dashboard, then delete the old one.

6. Publisher verification

Treat publisher verification as part of shipping a multitenant app registered after 8 November 2020. Microsoft applies a risk-based step-up consent policy to apps from unverified publishers: users in tenants other than your own can be blocked from consenting altogether, and the consent screen flags the publisher as unverified. A verified publisher gets a blue verified badge on that same screen instead. For a connector whose entire model is consumers in their own tenants authorising your app, this is the gate that decides whether they can connect at all.

What verification requires:

  • A verified Microsoft AI Cloud Partner Program account (formerly the Microsoft Partner Network), used as your organisation's partner global account.
  • The app registered with a work or school account, in a tenant associated with that partner global account.
  • A publisher domain set on the app (step 3), matching a domain verified on the tenant.
  • A user holding Application Administrator or Cloud Application Administrator in Entra ID plus Partner Admin or Account Admin in Partner Center, signing in with multifactor authentication.

Many Microsoft partners already meet these requirements. Mark your app as publisher verified has the step by step. If your organisation is not yet in the partner programme, start that enrolment first and ask your Microsoft contact for an expected timeline: it is the one step here that depends on someone outside your team.

7. Configure the credentials in the Apideck Dashboard

Microsoft Dynamics CRM is available through two Apideck unified APIs, and the credentials are configured per API. Open the settings for each API you use:

In each, switch on Use your own client credentials and enter:

  • Client ID: the Application (client) ID from step 5.
  • Client Secret: the secret Value from step 5.

The same app registration serves both APIs, and the scopes requested are identical for both, so you can paste the same pair of values into each. Review the scope list against the delegated permission you granted in step 4, then save.

Apideck sends consumers to https://login.microsoftonline.com/common/oauth2/v2.0/authorize to authorise, and exchanges and refreshes tokens at https://login.microsoftonline.com/common/oauth2/token. The /common endpoint is why the app has to be multitenant: it is what lets a user from any Entra tenant sign in to your app. Apideck stores the credentials and handles the token exchange and refresh for you.

8. What happens on the consumer's side

Your configuration is now complete, and the rest happens in each consumer's own tenant. Three things about that handoff are useful to know while you are still designing your onboarding:

  • Each consumer supplies their own organisation URL. Each consumer enters the address of their own Dynamics 365 environment as the Organisation URL setting in Vault, before authorising, and Apideck uses it as the target of the token request. There is nothing for you to configure here, and no value you can preset: it differs per consumer. The practical consequence is that one connection covers exactly one Dynamics 365 environment, so a consumer running separate environments needs one connection per environment. How a consumer finds that address is covered in the connection guide.
  • Consent may involve an administrator. As covered in step 4, that is the consumer tenant's policy rather than a fixed Microsoft rule. When a consumer's user cannot complete the consent screen themselves, the route forward is their own Microsoft administrator granting consent for the organisation; Microsoft documents this in Grant tenant-wide admin consent. Pointing at that page during onboarding turns a blocked consumer into a short internal request.
  • Tokens refresh automatically, within limits. Access tokens are short lived (roughly 60 to 90 minutes) and Apideck refreshes them. A refresh token expires after 90 days without use, which is not configurable, so a connection left completely idle for three months needs the consumer to authorise again.

One app registration covers all of this. Dynamics 365 has no separate identity host for testing, so the same Entra app and the same credentials serve every environment your consumers point a connection at, whether that is a production environment or a sandbox one.

FAQ and troubleshooting

A consumer's sign-in fails saying the application was not found in the directory

Usually one of three things:

  1. The app is not multitenant. Check Supported account types (step 1). A single-tenant registration can only ever be consented to inside your own tenant.
  2. The sign-in used the wrong account. The user has to sign in with an account in the tenant that owns the Dynamics 365 environment they want to connect, not a personal Microsoft account.
  3. Consent was blocked before the app could be provisioned. See the unverified publisher entry below and the tenant consent policy in step 4.

Complete publisher verification (step 6). Until then, users in tenants other than your own may be blocked from consenting, and administrators who can consent see the warning first.

Authorisation fails at the token step, or calls return 401 straight after connecting

Check the two values involved, in this order:

  1. The Client Secret. The Value versus Secret ID mix up from step 5 is the most frequent cause, followed by a secret that has passed its expiry date. Generate a fresh secret and paste its Value into the Apideck Dashboard.
  2. The Organisation URL the consumer entered. The token request is sent to whatever address the consumer supplied, so a value that is not their Dynamics 365 environment address fails here. Send them to the connection guide, which covers where to find the right one.

A connection works, but some records are missing or writes are rejected

The connection acts as the user who authorised it. Compare what that user can see and edit in Dynamics 365 directly: a security role that excludes a table or a business unit produces exactly this, and no change to the app registration can widen it. Re-authorising with an account that holds the right security roles is the fix.

A connection stopped working after a few months of no activity

The refresh token expired after 90 days of inactivity (step 8). The consumer authorises the connection again, and no change is needed on your side.

More information