Mastering the Business Central Administration API: A Complete Guide for SaaS Admins

Part 1: Authentication, Setup, and Your First Business Central Admin API Calls

The Business Central Administration API opens the door to a new way of working with your SaaS environments. Instead of clicking through the Administration Center, you can script your daily tasks, automate routine checks, and build tools that give you a clearer view of your tenant. This series is designed to guide you from your first authenticated call all the way to advanced operations like managing companies, reviewing app versions, and deploying PTE extensions.

There is a lot to cover, so we are going to do a multi-part series. The first part sets the foundation. We are going to walk through the setup, establish a secure connection, and explore a few simple calls that show how the API reflects the same information you see in the Administration Center. By the end, you will understand how the pieces fit together and be ready for the deeper topics that follow.

I’m going to do all these examples in PowerShell. If I can do it in PowerShell, then you can do it in any platform you like!

You are going to need an App Registration for your PowerShell to connect to Business Central Administration.

Open the Azure instance that your Business Central system is on at portal.azure.com. Open Entra ID and locate App Registrations. Click to create a new registration.

Name the App and click Register (at the bottom on the screen, not shown here)

From the next screen you will need the Application (client) ID and Directory (tenant) ID.

In the API Permissions you will need to add a few things. Click “Add Permission”, then find “Dynamics 365 Business Central”. Select “Application Permissions” and check the box for AdminCenter.ReadWrite.All.

Click the “Add Permission” button.

You will need to click the “Grant admin consent” button.

Lastly, you will need to click on “Certificates & Secrets”. Add a client secret, just remember to copy the value not the secret id. Save this, once you leave the page it is gone forever.

Now we go to our Business Central Admin Center. Select the “Microsoft Entra Apps” option from the left and click “Authorize Microsoft Entra app”. Enter Application (client) ID from our App Registration and click Save.

That was a lot of setup, but now we are ready to talk to the environment with PowerShell or any other tool that can do HTTPS.

The first step is to get the authentication token and build a header. This header will be used for all our BC Admin API Calls. I’m only going to show it once, but anytime you see the $headers in the PowerShell Script, it came from here.

$tenantId = "00000000-1111-2222-3333-444444444444"
$clientId = "55555555-6666-7777-8888-999999999999"
$clientSecret = "TheSecretFromAzureAppRegistration"
$baseUri = "https://api.businesscentral.dynamics.com"
$url = $baseUri+"/admin/v2.6"

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = "https://api.businesscentral.dynamics.com/.default"
}

$token = Invoke-RestMethod -Method Post `
    -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" `
    -Body $body

$headers = @{ Authorization = "Bearer $($token.access_token)" }

The first API call on the list is to grab a list of Environments.

$Environments = Invoke-RestMethod -Method Get `
    -Uri $url"/applications/BusinessCentral/environments" `
    -Headers $headers

$Environments.value

This spits out a lot of useful information:

friendlyName       : AardvarkLabsBlog-DirectionsNA
type               : Sandbox
name               : DirectionsNA
countryCode        : US
applicationFamily  : BusinessCentral
aadTenantId        : 3705b7c1-a1f0-461c-9692-0deedd973269
applicationVersion : 28.4.53241.53939
status             : Active
webClientLoginUrl  : https://businesscentral.dynamics.com/3705b7c1-a1f0-461c-9692-0deedd973269/DirectionsNA
webServiceUrl      : https://api.businesscentral.dynamics.com/v2.0/3705b7c1-a1f0-461c-9692-0deedd973269/DirectionsNA
locationName       : East US 2
platformVersion    : 28.0
databaseSize       : @{value=540672.0; unit=Byte}
ringName           : Production
appInsightsKey     : 

friendlyName       : AardvarkLabsBlog
type               : Production
name               : Production
countryCode        : US
applicationFamily  : BusinessCentral
aadTenantId        : 3705b7c1-a1f0-461c-9692-0deedd973269
applicationVersion : 27.5.46862.53716
status             : Active
webClientLoginUrl  : https://businesscentral.dynamics.com/3705b7c1-a1f0-461c-9692-0deedd973269/Production
webServiceUrl      : https://api.businesscentral.dynamics.com/v2.0/3705b7c1-a1f0-461c-9692-0deedd973269/Production
locationName       : South Central US
platformVersion    : 27.0
databaseSize       : @{value=573440.0; unit=Byte}
ringName           : Production
appInsightsKey     : InstrumentationKey=22222222-2222-2222-2222-222222222222;IngestionEndpoint=https://eastus-8.in.applicationinsights.azure.com/;LiveEndpoint=https://eas
                     tus.livediagnostics.monitor.azure.com/;ApplicationId=11111111-1111-1111-1111-111111111111

friendlyName       : AardvarkLabsBlog-AardvarkLabs
type               : Sandbox
name               : AardvarkLabs
countryCode        : US
applicationFamily  : BusinessCentral
aadTenantId        : 3705b7c1-a1f0-461c-9692-0deedd973269
applicationVersion : 28.4.53241.53939
status             : Active
webClientLoginUrl  : https://businesscentral.dynamics.com/3705b7c1-a1f0-461c-9692-0deedd973269/AardvarkLabs
webServiceUrl      : https://api.businesscentral.dynamics.com/v2.0/3705b7c1-a1f0-461c-9692-0deedd973269/AardvarkLabs
locationName       : East US 2
platformVersion    : 28.0
databaseSize       : @{value=475136.0; unit=Byte}
ringName           : Production
appInsightsKey     : 

friendlyName       : AardvarkLabsBlog-BCLatest
type               : Sandbox
name               : BCLatest
countryCode        : US
applicationFamily  : BusinessCentral
aadTenantId        : 3705b7c1-a1f0-461c-9692-0deedd973269
applicationVersion : 28.4.53241.53939
status             : Active
webClientLoginUrl  : https://businesscentral.dynamics.com/3705b7c1-a1f0-461c-9692-0deedd973269/BCLatest
webServiceUrl      : https://api.businesscentral.dynamics.com/v2.0/3705b7c1-a1f0-461c-9692-0deedd973269/BCLatest
locationName       : South Central US
platformVersion    : 28.0
databaseSize       : @{value=507904.0; unit=Byte}
ringName           : Production
appInsightsKey     :

Here you can see names, platforms, application versions, database size, and even the location that environment is hosted.

if I wanted just a single Environment, for example AardvarkLabs, then I can use the following URL.

$EnvironmentDetails = Invoke-RestMethod -Method Get `
    -Uri $url"/applications/BusinessCentral/environments/AardvarkLabs" `
    -Headers $headers

Now that we have an environment to focus on, let’s get a list of installed apps.

$InstalledApps = Invoke-RestMethod -Method Get `
    -Uri $url"/applications/BusinessCentral/environments/AardvarkLabs/apps" `
    -Headers $headers

$InstalledApps.value

This spits out a list of ALL the apps installed in the AardvarkLabs environment.

id        : 2654d7e7-9afd-4947-9e02-6bb8f3e0cd04
name      : Universal Print Integration
publisher : Microsoft
version   : 28.4.53241.53312
state     : installed

id        : e4e86220-cac0-4ec3-b853-7c2fa610399d
name      : Power BI Report embeddings for Dynamics 365 Business Central
publisher : Microsoft
version   : 28.4.53241.53312
state     : installed

id        : c526b3e9-b8ca-4683-81ba-fcd5f6b1472a
name      : Sales and Inventory Forecast
publisher : Microsoft
version   : 28.4.53241.53312
state     : installed

id        : c31ee575-3fc7-4388-98ee-d75aa2fc5f87
name      : Withholding Tax
publisher : Microsoft
version   : 28.4.53241.53312
state     : installed

id        : 64c9d5e2-7744-4866-bc0e-5ebc2898e651
name      : Error Messages with Recommendations
publisher : Microsoft
version   : 28.4.53241.53312
state     : installed

id        : 8fc50dfb-d338-4fd9-9499-5e44cc8cbf50
name      : Email - SMTP API
publisher : Microsoft
version   : 28.4.53241.53312
state     : installed

If I want to know which Apps have an available update.

$AvailableUpdates = Invoke-RestMethod -Method Get `
    -Uri $url"/applications/BusinessCentral/environments/AardvarkLabs/apps/availableUpdates" `
    -Headers $headers

$AvailableUpdates.value

appId        : 63ca2fa4-4f03-4f2b-a480-172fef340d3f
name         : System Application
publisher    : Microsoft
version      : 28.4.53241.53939
requirements : {}

appId        : 437dbf0e-84ff-417a-965d-ed2bb9650972
name         : Base Application
publisher    : Microsoft
version      : 28.4.53241.53989
requirements : {}

appId        : cc11c22e-5ca3-423f-8804-88cac6d91983
name         : Dynamics BC Excel Reports
publisher    : Microsoft
version      : 28.4.53241.53939
requirements : {}

appId        : ec255f57-31d0-4ca2-b751-f2fa7c745abb
name         : Shopify Connector
publisher    : Microsoft
version      : 28.4.53241.53921
requirements : {}

The last example for this post, do you want to know if there is a reported outage?

$OutageDetails = Invoke-RestMethod -Method Get `
    -Uri $baseUri"/admin/v2.29/support/reportedoutages" `
    -Headers $headers

$OutageDetails.value

There are no reported outages right now, so I don’t have any example outputs.

More details can be found in the Microsoft Learn page:

Business Central Administration Center API – Business Central | Microsoft Learn

The next part will cover APP management. We will review how to manage App Source extensions as well as PTE extensions. Subscribe to the blog so you can be the first to know about new posts. Also let me know in the comments if there are things you want to see how to accomplish with the Administration API.

Leave a comment Cancel reply

Join me on a journey through Business Central Development