ELI5 How to access BC Web Services/API with OAuth

Come join me in a theme-park-themed explaintion of how OAuth works with Business Central web services, check it out:

https://youtu.be/zsB-8v9LC7w

In this video, Erik breaks down OAuth authentication for Business Central web services using a theme park analogy. He walks through the entire process—from creating an Azure app registration to obtaining a bearer token and making API calls—making the often-confusing OAuth flow easy to understand.

The Theme Park Analogy

Erik introduces a brilliant analogy to explain how OAuth works with Business Central. Think of Business Central as a roller coaster sitting inside a theme park (Microsoft Azure/Cloud).

  • The Theme Park = Microsoft’s cloud (Azure Active Directory)
  • The Gate of the Theme Park = login.microsoftonline.com (the authentication endpoint)
  • The Roller Coaster = Business Central (the service you want to access)
  • The Token = Your proof of entry that lets you ride the roller coaster
  • The Ticket/App Registration = Your identity that gets you through the theme park gate
  • The Password/Secret = Proof that you are who you claim to be

To ride the roller coaster (access Business Central), you first need to get through the theme park gate (authenticate with Azure). You can’t skip straight to the roller coaster. At the gate, you present your ticket (app registration) and your password (client secret), and in exchange, you receive a token. Then you walk over to the roller coaster and present that token to get in.

Step 1: Create an App Registration in Azure

The first step is to create your “ticket” — an app registration. Navigate to portal.azure.com and search for App registrations.

When creating a new registration:

  • Give it a name (Erik used “Theme Park” for demonstration purposes)
  • Set the supported account type — in this case, accounts within your own tenant only (no outsiders)
  • Click Register

Once registered, you’ll receive an Application (client) ID. This is your user ID — copy it to your clipboard.

Step 2: Create the Application User in Business Central

Before OAuth, you’d typically use a real user account (like “Erik from accounting”) with a web service key for basic authentication. That approach is no longer supported. Instead, you now work with application users — think of them as non-human, machine users.

In Business Central, search for Azure Active Directory Applications. This is where you define your application users. Create a new entry:

  1. Paste the Application (client) ID you copied from Azure
  2. Give it a descriptive name
  3. Enable it
  4. Assign appropriate permissions (e.g., D365 BUS PREMIUM for access, SUPER DATA for broad data access during testing)

An important note: application users do not require a license. You can grant them access to all companies, and you should follow the principle of least privilege — only give the application access to what it needs.

Step 3: Configure API Permissions in Azure

Back in Azure, navigate to API Permissions for your app registration. By default, the app can only do a “look in the mirror” (read its own profile via Microsoft Graph). You need to add permissions for Business Central.

  1. Click Add a permission
  2. Select Dynamics 365 Business Central
  3. Choose Application permissions (not Delegated, since this is an application logging in, not a real user)
  4. Select API.ReadWrite.All — this gives the application permission to perform read/write operations
  5. Click Grant admin consent — an administrator must approve these permissions

The distinction between Delegated and Application permissions is important: Delegated permissions require a user to interactively log in, while Application permissions are for machine-to-machine communication with no user present.

Step 4: Create a Client Secret

Navigate to Certificates & secrets in your app registration and create a new client secret:

  1. Click New client secret
  2. Set an expiration period (Erik chose 3 months for the demo)
  3. Copy the Value (not the ID) immediately — you won’t be able to see it again

This secret acts as the password. When your application approaches the “gate” (login.microsoftonline.com), it presents both the client ID (who you are) and the client secret (proof you are who you claim to be). In exchange, the gate hands you a bearer token.

Step 5: The Code — Putting It All Together

Erik walks through a C# application that demonstrates the complete OAuth flow. Here’s how the process works in code:

Requesting the Token

First, you build a request to login.microsoftonline.com/{tenantId}/oauth2/v2.0/token with the following parameters:

  • client_id — your Application (client) ID from the app registration
  • client_secret — the secret value you created
  • grant_type — set to client_credentials
  • scope — set to https://api.businesscentral.dynamics.com/.default to indicate you want access to Business Central

The response includes:

  • A bearer token (a long encoded string)
  • An expiration time (typically one hour)
  • Optionally, a refresh token (though in client_credentials flow, you typically don’t get one — you just request a new token)

Calling Business Central

With the token in hand, you make your API call to Business Central. Instead of the old basic authentication (Base64-encoded username:password), you simply add an Authorization header with the bearer token:

Authorization: Bearer {your_token_here}

The request goes to something like https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/v2.0/chartOfAccounts, and you get your data back.

Reusing the Token

The token works like a New York subway ticket that comes out the other side — you can reuse it. Erik demonstrates making multiple API calls with the same token. You can keep using it for up to an hour, after which you need to request a new one from the authentication endpoint.

The Two-Layer Security Model

Erik demonstrates an important concept: there are two independent layers of security at play.

Scenario 1: Disable the App in Business Central

If you disable the application in Business Central’s Azure Active Directory Applications page:

  • The gate (Azure AD) still happily issues a token — it has no idea what Business Central has configured
  • But when you present that token to Business Central, you get an Unauthorized response
  • The token was valid for entry into the “theme park,” but the “roller coaster” refused entry

Scenario 2: Delete the App Registration in Azure

If you delete the app registration in Azure but leave the application enabled in Business Central:

  • Business Central says “sure, come on in!”
  • But you can never get a token because the gate returns a Bad Request — your ticket is no longer valid
  • You never even reach Business Central’s doorstep

This two-layer model is part of what makes OAuth confusing, but it also provides robust security. You have control at both the Azure level and the Business Central level.

Reference: Sample AL Extension Code

For those building extensions that expose web services, here’s the sample codeunit Erik had in the project that could be published as a web service:

codeunit 50119 "WCF Test"
{
    procedure Ping(parm: Text): Text
    begin
        exit(Parm + ' ' + Parm);
    end;
}

Summary

The OAuth flow for Business Central web services boils down to these key steps:

  1. Create an App Registration in Azure Portal — this is your identity/ticket
  2. Create an Application User in Business Central’s Azure AD Applications page using the client ID
  3. Configure API Permissions in Azure — add Business Central with Application permissions (API.ReadWrite.All) and grant admin consent
  4. Create a Client Secret in Azure — this is your password
  5. Request a Token from login.microsoftonline.com using your client ID, secret, and desired scope
  6. Call Business Central APIs using the bearer token in the Authorization header
  7. Reuse the token for up to an hour, then request a new one

Remember: authentication happens at two levels. Azure AD controls whether you can get a token at all (the theme park gate), and Business Central controls whether that token actually grants you access to data (the roller coaster gate). Both must be properly configured for the flow to work.

Picture of hougaard

hougaard