How to connect Microsoft Dynamics 365 Business Central

Connecting Business Central takes three actions: authorize with your Microsoft account, select the Business Central Environment and save, then select the Default Company and save. There are no credentials to copy and paste — Apideck runs the OAuth flow and refreshes the access token afterwards, so the connection keeps working without you re-entering anything.

The two selections happen in that order for a reason: companies live inside an environment, so the company list can only be loaded once the environment is saved. Plan for two saves rather than one.

Prerequisites

• Business Central online (SaaS), any edition. On-premises Business Central deployments are not supported by this connector.
• A Business Central user account with access to the environment and company you want to connect. Any Business Central user can authorize the connection — no administrator role is needed for this step.
• One-time consent in your Microsoft Entra tenant. A Microsoft Entra administrator in your organization grants consent once for the whole tenant. It is often already in place; if it is not, Microsoft tells you during sign-in (see Microsoft asks for admin approval).
• Know which environment and company this connection is for. A tenant can have a production environment plus sandboxes, and each environment can hold several companies.

To see what your account can reach, sign in at businesscentral.dynamics.com. Administrators can review the full environment list in the Business Central admin center — see Microsoft's Managing production and sandbox environments.

1. Authorize with Microsoft

1. Open the Microsoft Dynamics 365 Business Central connection in Apideck Vault.
2. Click Authorize. You are redirected to Microsoft to sign in.
3. Sign in with the Business Central account you want the connection to use, review the permissions listed on the consent screen, and accept.

The consent screen names the application requesting access. That is either the Microsoft Entra application registered by the provider whose integration you are setting up, or Apideck when the integration is still using Apideck's shared sandbox credentials for testing. Read the permissions before accepting; if the access shown is wider than you expect, raise it with that provider rather than accepting and reversing it later.

You are never asked for a redirect URL, a tenant ID, or a client secret. Your Microsoft Entra tenant ID is recorded automatically from the authorization.

2. Select your Environment — then save

After Microsoft redirects you back to Vault, an Environment dropdown appears. Its options are read live from your Business Central tenant, so it lists the environments — production and sandbox — that the account you just authorized with can reach.

1. Select the environment this connection should use.
2. Click Save.

Save before moving on. The Default Company dropdown is populated by reading the companies inside the saved environment, so it has nothing to offer until this selection is stored.

3. Select your Default Company — then save

With the environment saved, the Default Company dropdown lists the companies in that environment.

1. Select the company this connection should use.
2. Click Save.

Both selections are required. Neither has a default: until an Environment and a Default Company are saved, the connection is not usable and requests through it will not return Business Central data.

If you later switch the connection to a different environment, re-check the Default Company — company selections belong to the environment they were made in.

4. Journal batch names (only if your integration uses journal entries, expenses, or bill payments)

Three resources need one extra piece of information on the connection, alongside Environment and Default Company — the code of an existing Business Central journal batch. Which journal template that batch has to sit under differs by resource: journal entries and expenses take a batch under the General Journals template, while bill payments require one under the vendor Payment Journals template.

Resource	Setting	Batch must exist under	Example value
Journal entries	Default journal batch name	General Journals	DEFAULT
Expenses	Expenses journal batch name	General Journals	EXPENSES
Bill payments	Bill payments journal batch name	Payment Journals	CASH

Business Central identifies a batch by template and code, so the same code can exist under General Journals and not under Payment Journals. For bill payments, only a Payment Journals batch is accepted — a code that exists solely under General Journals is rejected (see Troubleshooting).

Each setting is required before that resource works, and the batch must already exist in the company you selected — it cannot be created from here, and a different batch cannot be chosen per request. Records are created in the batch you name, and draft reads are scoped to it as well: listing any of the three resources unfiltered (or filtered to draft) with a batch name that is unset, misspelled, or under the wrong template fails with an explicit journal-batch error. When the batch exists, those listings return records from that batch only, so records created in another batch will not appear. Reads that target posted records are served from the general ledger instead and do not involve the batch — filtering a list by a posted status, and fetching a single bill payment that has been posted, both work even when the batch setting is wrong.

To find the codes, open Business Central and use the search icon: General Journal Batches for the journal-entries and expenses settings, Payment Journals for the bill-payments setting. Microsoft documents these pages in Working with general journals to post directly to G/L. If you are unsure which batch the integration should post to, agree it with your finance team before saving — posted entries land wherever this points.

Notes

• Token refresh is automatic. Apideck refreshes the short-lived access token for you; there is nothing to re-enter while the connection is in regular use.
• A connection left unused for 90 days needs re-authorizing. Microsoft Entra expires the stored refresh token after 90 days of inactivity, and that window is not configurable. Regular use keeps that refresh token alive, so the 90-day window is what re-authorization guards against on a dormant connection — restore one by opening it in Vault and clicking Authorize again.
• Your access governs the connection's access. What the connection can read and write is governed by the authorizing user's Business Central permissions. If that user's access is reduced, disabled, or removed later, the connection is affected too.
• Testing uses the same setup as production. Sandboxes appear in the same Environment dropdown as production. Microsoft's sandbox environment overview covers how to get one. Prefer a sandbox for first tests — writes through the connection create real Business Central records.

Troubleshooting

The connection still isn't usable after I authorized. Authorization alone does not finish setup. Open the connection and confirm that both Environment and Default Company are selected and saved (see steps 2 and 3).

The Environment dropdown is empty. Work through these in order:

1. Confirm the account you authorized with can sign in at businesscentral.dynamics.com and reach at least one environment.
2. Confirm the tenant is Business Central online. On-premises deployments are not supported and will not list environments here.
3. If both hold, re-run Authorize with the account that has the access.

The Default Company dropdown is empty. Almost always the Environment is not saved yet — the company list is read from the saved environment, so select the environment and click Save first. If the environment is saved and the list is still empty, confirm the authorizing user can open a company in that environment in Business Central.

Microsoft says admin approval is needed. Consent for the application has not been granted in your Microsoft Entra tenant yet. It is a one-time action per tenant, performed by a Microsoft Entra administrator in your organization — forward the request to them, then run Authorize again. You do not need to be that administrator to use the connection afterwards.

"Journal batch '<name>' exists under the General Journals template but not the Payment Journals template." The code entered as the Bill payments journal batch name names a General Journals batch, and bill payments need one under the vendor Payment Journals template. This message appears when creating a payment and when listing payments — both resolve the configured batch before the request goes out. In Business Central, open the Payment Journals page, create the batch there with a matching balancing account, and enter that batch's code in the setting. Reusing the General Journals code will keep failing with this message even though the code exists.

The connection works, but returns another company's data. Check the Default Company selection. The connection reads and writes the company saved there.

The connection worked and later stopped. The usual causes, in order:

1. It sat unused for more than 90 days — re-authorize (see Notes).
2. The authorizing user's Business Central access changed or their account was disabled — re-authorize with an account that has the access.
3. The client secret on the Microsoft Entra application behind the integration expired. That is held by the provider whose integration you are using, not by you — report it to them, since every connection using that application is affected.

Journal entries, expenses, or bill payments return nothing or fail. Check the journal batch name for that resource (step 4): it must exactly match the code of a batch that exists in the saved company, under the template that resource requires. A name that is unset, misspelled, or under the wrong template fails draft listings for all three resources with an explicit journal-batch error (listings filtered to a posted status read from the general ledger instead and are unaffected). If a draft listing succeeds but records are missing, they were likely created in a different batch — draft lists return only the configured batch's records.

Still stuck? Contact Apideck Support.