INTEGRATION • AUTHENTICATION

OAuth 2.0 Authentication in Business Central AL

Learn how OAuth 2.0 works with Microsoft Dynamics 365 Business Central, Microsoft Entra ID, access tokens, scopes and service-to-service integrations. This guide focuses on practical concepts developers need when connecting Business Central to external APIs.

Dynexal · Business Central AL Development

What is OAuth 2.0?

OAuth 2.0 is an authorization framework that allows an application to obtain limited access to a protected resource without exposing a user's password to the application. In Business Central, OAuth is commonly used with Microsoft Entra ID to authenticate API and web-service calls.

For integrations that must run without a user being present, service-to-service (S2S) authentication uses the OAuth 2.0 client credentials flow.

Developer takeaway: Think of OAuth as a secure way to obtain an access token. Your integration sends that token with the API request instead of sending a Business Central username and password.

OAuth 2.0 flow in simple terms

Register an application in Microsoft Entra ID.
Give the application the required Business Central permissions.
The application authenticates with Microsoft Entra ID.
Microsoft Entra ID issues an access token.
The client sends the token in an HTTP Authorization header.
Business Central validates the token and permissions before serving the API request.

User authentication vs service-to-service authentication

OAuth can be used for interactive scenarios where a user signs in and for unattended integrations. For background jobs, middleware, scheduled synchronization and other integrations that do not require a user interaction, S2S authentication uses the OAuth 2.0 client credentials flow.

Microsoft Entra ID app registration

A typical S2S integration starts by registering an application in the Microsoft Entra tenant. The application has an identity represented by values such as a client ID and tenant ID. The application is then granted access in Business Central.

The Business Central setup requires registering the application in Microsoft Entra ID and granting the application access in Business Central.

Important OAuth terms

Tenant ID: Identifies the Microsoft Entra tenant.
Client ID: Identifies the registered application.
Client secret: A credential used by a confidential client. Treat it as a secret and never hard-code it in source control.
Access token: A short-lived credential presented to the protected API.
Scope: Defines the target resource and permissions requested by the client.
Authorization server: Microsoft Entra ID issues tokens for the integration.

Client credentials flow

For unattended Business Central integrations, the client credentials flow is a common pattern. The application authenticates with its own identity rather than impersonating a user. The Business Central resource scope is https://api.businesscentral.dynamics.com/.default.

POST https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<clientId>
&client_secret=<clientSecret>
&scope=https%3A%2F%2Fapi.businesscentral.dynamics.com%2F.default

The token endpoint returns an access token. The integration then uses that token when calling Business Central.

Calling a Business Central API with the token

After obtaining the access token, the client sends it as a Bearer token.

GET https://api.businesscentral.dynamics.com/v2.0/<environment>/api/v2.0/companies
Authorization: Bearer <access_token>

Business Central API endpoints use a predictable structure containing the environment and API route. Custom APIs also include the publisher, group and version in the route.

OAuth with Business Central custom APIs

Custom API pages are exposed through the Business Central API stack. An API page can define properties such as APIPublisher, APIGroup and APIVersion, which become part of the endpoint route.

page 50120 "Customer Integration API"
{
    PageType = API;
    SourceTable = Customer;
    APIPublisher = 'dynexal';
    APIGroup = 'integration';
    APIVersion = 'v1.0';
    EntityName = 'customer';
    EntitySetName = 'customers';
    ODataKeyFields = SystemId;

    layout
    {
        area(content)
        {
            field(id; Rec.SystemId) { }
            field(number; Rec."No.") { }
            field(name; Rec.Name) { }
        }
    }
}

Authentication and authorization are separate from the API object's AL definition. The API endpoint must still be protected by appropriate Business Central permissions.

Calling OAuth-protected APIs from AL

When Business Central itself acts as the client of an external OAuth-protected service, AL can use HttpClient to send HTTP requests. The access-token acquisition flow depends on the external provider. Business Central also includes OAuth 2.0 management functionality in the application for supported OAuth scenarios.

HttpClient.DefaultRequestHeaders().Add(
    'Authorization',
    StrSubstNo('Bearer %1', AccessToken)
);

if not HttpClient.Get(Endpoint, Response) then
    Error('The HTTP request could not be sent.');

For production integrations, keep secrets out of source code and use an appropriate secure configuration or secret-management approach.

OAuth vs Basic Authentication

Business Central documentation recommends OAuth rather than web service access keys for modern authentication. Access keys using Basic Authentication are deprecated and aren't supported for Business Central online. OAuth provides short-lived access tokens and integrates with Microsoft Entra ID.

Security warning: Never publish client secrets, access tokens or other credentials in GitHub repositories, screenshots, tutorials or frontend JavaScript. If a secret is exposed, rotate it immediately.

Common OAuth errors

401 Unauthorized

Usually indicates that the access token is missing, invalid, expired or intended for a different resource.

403 Forbidden

The token may be valid, but the application or user does not have the required Business Central permissions.

Invalid audience

Check that the token was requested for the correct Business Central resource. Incorrect audiences can cause authentication failures, particularly in on-premises configurations.

Invalid client

Verify the tenant, client ID, client credential and Microsoft Entra app configuration.

OAuth 2.0 best practices

Use OAuth 2.0 instead of deprecated Basic Authentication for modern Business Central web-service integrations.
Use S2S/client credentials for unattended integrations where appropriate.
Never hard-code client secrets in AL source code.
Request only the permissions required by the integration.
Handle token expiration and acquire a new token when necessary.
Log useful error information without logging secrets or full access tokens.
Use HTTPS for all production API traffic.
Separate development, test and production application registrations or configurations where appropriate.

Real-world integration architecture

External App / Middleware
        |
        | OAuth 2.0
        v
Microsoft Entra ID
        |
        | Access Token
        v
Business Central API
        |
        v
Tables / Business Logic

This architecture is useful for e-commerce, CRM, warehouse, payment, analytics and other enterprise integrations where an external system needs controlled access to Business Central.

Frequently asked questions

Is OAuth 2.0 required for Business Central APIs?

Business Central supports OAuth for web services and APIs, and Microsoft recommends OAuth for modern web-service authentication.

What is S2S authentication?

Service-to-service authentication allows an application to access Business Central without a user interaction. It uses the OAuth 2.0 client credentials flow.

Can OAuth be used with custom API pages?

Yes. Custom API pages are part of the Business Central API stack, and access is protected by the authentication and authorization configured for the Business Central environment.