Skip to content

Integrating Microsoft Dynamics 365 BC (Inventory)

Auth: OAuth 2.0 · Partner program: not required · Setup time: about 30 minutes · Last verified: 2026-05-23

Dynamics 365 Business Central is Microsoft’s SMB ERP. The adapter targets the BC v2.0 REST API + custom API Pages and surfaces items, item categories, item ledger entries, warehouses (locations), and vendors into the canonical inventory schema.

  • OAuth 2.0 via Microsoft Entra ID (formerly Azure AD) — there are no BC-native auth endpoints. Two flows are supported:
    • Authorization Code grant (delegated): authorize at https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize, exchange at https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token. Uses the connecting user’s BC permissions.
    • Client Credentials grant (service-to-service / S2S): same token endpoint, no user prompt. Requires the BC admin to grant the app consent in Entra and map the app to a BC user via AAD Applications in BC.
  • Basic auth with Web Service Access Keys was deprecated for BC Online and removed by 2022 — OAuth 2.0 is mandatory.
  • Production tokens use the resource scope https://api.businesscentral.dynamics.com/.default.
  1. A Dynamics 365 Business Central tenant (cloud https://businesscentral.dynamics.com or on-premise with OAuth configured).
  2. An App Registration in Entra ID under the customer (or partner) tenant:
    • Add API permissions → APIs my organization uses → Dynamics 365 Business Central.
    • For S2S: API.ReadWrite.All + Automation.ReadWrite.All (Application permissions); grant admin consent.
    • For delegated: user_impersonation (Delegated).
  3. For S2S only: in BC, add the app to Microsoft Entra Applications and assign permission sets covering inventory (typically D365 READ + D365 BUS PREMIUM or a tighter custom set).
  1. Open /platforms in the admin UI, filter to Inventory, click Microsoft Dynamics 365 BC (Inventory).
  2. Fill Configure:
    • clientId — your Entra App Registration’s Application (client) ID.
    • clientSecret — a client secret from the App Registration.
    • tenantId — the BC customer’s Entra tenant ID (or common for multi-tenant apps).
    • environmentName — the BC environment (e.g. Production, Sandbox).
    • companyId — the BC company GUID inside that environment.
    • redirectUri — ${PUBLIC_BASE_URL}/auth/inventory/dynamics-365-bc-inventory/callback.
  3. Enable the adapter.
  • Delegated: https://api.businesscentral.dynamics.com/user_impersonation + offline_access (for refresh).
  • S2S: https://api.businesscentral.dynamics.com/.default (resource-default; the granted Application permissions take effect).

Avoid declaring per-method scopes — BC’s OAuth permission model is coarse and managed in Entra.

BC supports Webhook Subscriptions on standard and custom API Pages: POST /api/v2.0/subscriptions with a notificationUrl. BC validates ownership by POSTing a validationToken query parameter to the URL — the adapter responds with the token within 5 seconds. Each subsequent delivery includes a clientState field you can use as a shared secret check; BC does not sign payloads with HMAC.

Subscribe to items, itemCategories, and companies/{id}/items resources for the inventory surface.

  • Company GUID is in every URL. /v2.0/{tenantId}/{environment}/api/v2.0/companies({companyId})/items — pin all three.
  • API Pages vs OData UI pages. API Pages (/api/v2.0/...) are 30-50% faster than legacy OData; Microsoft is deprecating OData UI page endpoints in 2027 Wave 1.
  • S2S apps must be mapped to a BC user. Granting Entra consent is necessary but not sufficient; BC requires the explicit “Microsoft Entra Applications” mapping before requests succeed.
  • No HMAC on webhooks. Use clientState plus IP allow-listing if you need stronger guarantees.