> For the complete documentation index, see [llms.txt](https://docs.zwapgrid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/business-central.md).

# Business Central

Complete Business Central onboarding from your client backend.

**Preview** · [What this means for your integration](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#preview)

Your backend completes Microsoft authorization and selects a tenant, environment and company. You send the tokens and that selection to Zwapgrid. **Zwapgrid checks access and takes over token refresh.**

First, complete the [shared prerequisites and example setup](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#before-you-start).

## What you need

* A Microsoft Entra confidential **web application**: an application whose secret is kept on your backend. See the [Business Central setup guide](https://docs.zwapgrid.com/client-portal/systems/setup-guides/business-central.md) for registration and test access.
* A Published Business Central System Setting containing that application's ID and secret, belonging to your Zwapgrid client. Your backend also needs those credentials for code exchange.
* Your backend callback registered as a **Web** redirect in Entra.
* The **Dynamics 365 Business Central → Delegated permissions → `user_impersonation`** permission configured in your Entra application. The authorizing user must be able to discover environments, list companies and perform the accounting operations you need.

For this headless flow, configure the delegated permissions above even if you already followed the setup guide's application-permission instructions. Register a Web callback so your backend can receive a refresh token suitable for ongoing access.

## OAuth scopes

Zwapgrid needs these scopes to access your customer's accounting data:

```
https://api.businesscentral.dynamics.com/.default offline_access
```

## 1. Prepare the connection

1. Use the [Consent created in the shared workflow](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#1-create-a-consent). Make sure `systemsSettings.businesscentral` contains your published setting ID.
2. Start Microsoft authorization using the authorization URL below, your application ID, registered callback, delegated scopes and the `state` value described in the [shared workflow](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#2-follow-your-systems-authorization-steps).
3. At your callback, validate `state` and exchange the code on your backend using the token URL below. Keep the access token and the latest refresh token.
4. Call `GET https://api.businesscentral.dynamics.com/environments/v1.2` with the bearer access token. Select an environment. Keep its `aadTenantId` as `tenantId` and its `name` as `environment`.
5. List companies with `GET https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/v2.0/companies`. URL-encode the environment path segment. Select the company's `id` as `companyId`. If you change environments, select a company again from the new environment.
6. If your backend is refreshing these tokens, stop it and wait for any refresh in progress to finish. Send the latest tokens and selected company details once. Keep your refresh process stopped while Zwapgrid handles the request or you check its result.

Use these Microsoft endpoints:

| Request                 | URL and parameters                                                                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Authorization (browser) | `https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `scope` and `state`.                                             |
| Code exchange (backend) | Form-encoded POST to `https://login.microsoftonline.com/organizations/oauth2/v2.0/token` with `grant_type=authorization_code`, `code`, `redirect_uri`, `scope`, `client_id` and `client_secret`. |

## 2. Send the request

```json
{
  "source": "businesscentral",
  "credentials": {
    "accessToken": "<latest-delegated-access-token>",
    "refreshToken": "<latest-refresh-token>",
    "tenantId": "<selected-Entra-tenant-UUID>",
    "environment": "<selected-environment-name>",
    "companyId": "<selected-company-UUID>"
  }
}
```

Every field is required. Access tokens are limited to 8192 characters, refresh tokens to 4096, and environment names to 100 letters, digits, underscores or hyphens. Tenant and company IDs must be non-empty UUIDs. Do not send the application secret, code, redirect URI, PKCE verifier or setting ID.

Zwapgrid refreshes the tokens using your selected application and checks access to the exact tenant, environment and company before saving the connection.

Replace the placeholders and save this body as a protected `connection.json` on your backend. Set the [example variables](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#set-up-the-examples), including a new UUID in `CORRELATION_ID`, then send the request once:

```sh
curl --request POST \
  "$CONSENTS_API_BASE_URL/api/v1/consents/$CONSENT_ID/connection" \
  --header "x-api-key: $ZWAPGRID_API_KEY" \
  --header "x-correlation-id: $CORRELATION_ID" \
  --header 'Content-Type: application/json' \
  --data-binary @connection.json
```

## 3. Check the result

Expect HTTP 201 with `source: businesscentral` and `state: completed`. [Optionally verify the connection](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#optional-verify-the-connection) against the selected company.

Zwapgrid owns refresh after confirmed creation. Do not keep refreshing these tokens in your backend or submit them for another connection. After an uncertain response, keep refresh paused and use GET. A missing connection does not prove the submitted refresh token remains current; authorize again if you cannot confirm whether the tokens are still valid.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/business-central.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
