Connecting Business Central online
An administrator's guide to letting the Magic CRM sync agent reach Business Central online, and installing the agent on a Windows server.
Magic CRM syncs with Business Central through a small program, the sync agent, that you install on a machine of yours. This guide is for Business Central online: you open it at https://businesscentral.dynamics.com/… with a Microsoft account. For a Business Central on a server of yours or your partner’s, see Business Central on-premises.
The agent signs in to Business Central as an application registered in Microsoft Entra. Nothing has to be opened to the internet: the agent only makes outgoing HTTPS connections, to Business Central, to Microsoft’s sign-in service and to Magic CRM. Business Central’s credentials stay in the agent’s configuration on your machine; Magic CRM never sees them.
What the sync exchanges is described in What the Business Central sync sends.
Before you start
You need two administrators’ rights, which may be the same person:
- In Microsoft Entra: Global Administrator, Privileged Role Administrator, or (Cloud) Application Administrator, in the directory Business Central lives in.
- In Business Central: the right to add Microsoft Entra applications and give them permission sets.
- In Magic CRM: an owner or admin of the organization.
You will end with five values: the API address, the company id, the tenant id, the application (client) id and a client secret.
1. Register an application in Microsoft Entra
At the Azure portal, as an administrator of the directory Business Central lives in:
- Microsoft Entra ID → App registrations → New registration. Give it a name such as Magic CRM sync and choose Accounts in this organizational directory only. Under Redirect URI, choose Web and enter
https://businesscentral.dynamics.com/OAuthLanding.htm. The agent itself never uses it, but Business Central’s Grant Consent button in step 2 fails without it. - From the overview, note the Application (client) ID and the Directory (tenant) ID.
- API permissions → Add a permission → Dynamics 365 Business Central → Application permissions → API.ReadWrite.All → Add. This lets the application ask at all; what it may touch is decided in step 2.
- Still on API permissions, choose Grant admin consent for your tenant. The Status column then shows a green tick. If the button is greyed out, your account has no admin role in this directory, even if it owns the Business Central subscription: check Users → your user → Assigned roles, and check at the top right that you are in the right directory and not there as a guest.
- Certificates & secrets → New client secret. Copy the Value (not the Secret ID) now: it is shown only once. Note when it expires: the sync stops that day, and the agent’s log says the secret has expired.
2. Let the application into Business Central
In Business Central (in a sandbox environment first, if you have one), search for Microsoft Entra Applications and choose New:
-
Client ID: the application id from step 1, and a description. Leave State as Disabled for now.
-
Add permission sets in the User Permission Sets table on the same card, one row per set. The table can only be changed while State is Disabled. Give only what the sync touches:
The sync Needs reads and writes customers, contacts reads, and creates when asked to items, sales quotes reads sales orders and their lines, item ledger entries D365 BASICplus the customer, item and sales-document sets is the usual starting point; the exact names vary by version and localisation. Nothing is ever deleted through the sync.For the first run, give read permissions only. A write the sync attempts then fails visibly in Magic CRM instead of changing a customer, and the reads are what need checking first.
-
Set State to Enabled, and accept the message that a user is created for the application. No user licence is needed for an application.
-
Choose Grant Consent at the top of the card. An administrator of the directory signs in and accepts, and Business Central says consent was granted. The error
AADSTS500113: No reply address is registeredmeans the redirect URI from step 1 is missing.
3. Find the environment and the company
- The environment is in Business Central’s address bar, after the tenant id:
…/<tenant id>/<environment>?company=…. When nothing stands between the tenant id and?company=, it is the default environment, usuallyProduction. The exact names are listed under Environments in the Business Central admin center. - The API address is then
https://api.businesscentral.dynamics.com/v2.0/<tenant id>/<environment>/api/v2.0. - The company id: one agent syncs one company. To list the companies with their ids, and to prove the setup works, from any machine with
curlandjq:
TOKEN=$(curl -s -X POST "https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token" \
-d grant_type=client_credentials \
-d client_id=<client id> \
--data-urlencode client_secret=<client secret> \
-d scope=https://api.businesscentral.dynamics.com/.default | jq -r .access_token)
BASE="https://api.businesscentral.dynamics.com/v2.0/<tenant id>/<environment>/api/v2.0"
curl -H "Authorization: Bearer $TOKEN" "$BASE/companies"
curl -H "Authorization: Bearer $TOKEN" "$BASE/companies(<company id>)/customers?\$top=1"
| Answer | Means |
|---|---|
TOKEN is null |
A wrong tenant, application id or secret. Run the first command without | jq and read error_description |
AADSTS700016: Application … was not found in the directory |
One of the two ids is wrong. The client id must be the Application (client) ID, not the Object ID or the Secret ID; the tenant must be the one in Business Central’s address bar |
401 from Business Central |
Step 2 has not been done in this environment, or the application is not Enabled |
403, or an error naming a permission |
The permission sets do not cover that kind of record |
404 |
The environment’s name or the company id |
200 and a customer |
Business Central’s side is finished |
4. Get a pairing token
In Magic CRM, as an owner or admin: Admin → ERP, then Connect (once per organization), then Add an agent. Name it after where it runs, such as “the accounting server”. Copy the pairing token: it is shown once, and works for one pairing only. If you lose it, revoke that agent and add another.
5. Install the agent on Windows
The agent runs on any machine with outgoing HTTPS. On a Windows server:
- On the same page, Admin → ERP, choose Download the agent for Windows. It is an MSI installer. Check it against the SHA-256 shown on the page, in PowerShell:
Get-FileHash .\<file>.msi -Algorithm SHA256. - Run the installer. It asks one thing, the port of its configuration page: 7050, unless another program already uses it.
- From the Start menu, open Configure Magic CRM Agent. Windows asks for an administrator’s permission, and the page opens in your browser, reachable from this machine only:
- Pairing: paste the token.
- The ERP: the API address, the company id, the tenant id, the application id and its secret.
- Check: both lines must show a tick.
- Leave The service stopped for now, until the checks below.
The agent is installed in C:\Program Files\Magic CRM Agent and runs as the Windows service Magic CRM Agent, which starts with Windows and is restarted if it stops. Its folder is closed to everyone but administrators and the service itself, and its secrets are encrypted so that a copy of its configuration file cannot be used on another machine.
Without a desktop, or on many servers, the installer runs silently: msiexec /i .\<file>.msi /qn (add UI_PORT=7051 for another port). Then, in an elevated PowerShell in the installed folder:
.\agent.exe pair <token> # joins this agent to your organization
.\agent.exe configure -auth oauth # asks for the address, company, tenant, application id and secret
.\agent.exe status # both lines must say ok
6. Before the first sync
- Check the switches under Admin → ERP → Connection, which decide what the first sync may write:
- New companies become customers in the ERP should be off to begin with: your accountant first decides what a new customer gets in Business Central.
- Customers the ERP has and we do not become companies here is on by default: the first sync makes a company of every customer of yours that matches none in Magic CRM.
- Run one round by hand:
.\agent.exe oncein the installed folder, then look at Admin → ERP → Activity for the run and its tasks. With read-only permissions in Business Central, any write the sync attempts fails, as it should. - Start it: Start on the configuration page, or
Start-Service MagicCRMAgent. Within a minute, Admin → ERP shows the agent as seen, and from then on it starts with the machine. - Customers whose name matches a company of yours wait under Admin → ERP → Waiting for you. Nothing happens to them until someone answers.
When you are satisfied with the reads, give the application the write permissions in Business Central (set State to Disabled, change the permission sets, then Enabled again).
When something fails
What status, or Check on the configuration page, says when the Business Central line fails:
| Message | Means |
|---|---|
the sign-in service refused the application, with 401: invalid_client … |
The tenant, the application id or the secret; Microsoft’s words after it say which |
answered 401 to GET /customers |
The application is not in Microsoft Entra Applications for that environment |
| No status at all | Business Central cannot be reached from this machine |
A task Business Central refused shows as Failed in Admin → ERP → Activity, with Business Central’s own message. A task that could not get through after five attempts is Parked. Retry puts either back.
Upgrading, stopping and removing
- Upgrade: run the new installer. The configuration and the port are kept, and the service is started again.
- Stop at any moment, with Stop on the configuration page or
Stop-Service MagicCRMAgent: nothing is lost and nothing is applied twice. Edits made in Magic CRM meanwhile wait, and go when the agent is back. - Remove: uninstall Magic CRM Agent from Settings → Apps in Windows. The configuration and logs are kept unless the uninstall is run with
PURGE=1. Then choose Revoke beside the agent in Admin → ERP, which ends its access at once.