Chỉnh sửa

Chia sẻ qua

The Business Central Admin Center API

  • Bài viết

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

The Business Central administration center API enables administrators to programmatically do administrative tasks for a Business Central tenant. With the API, administrators can, for example:

  • Query and work with production and sandbox environments for the tenant.
  • Set up administrative notifications.
  • View telemetry for events on the tenant.

For more information about administrative capabilities, see The Business Central Administration Center. This article describes the API contracts for these administrative capabilities.

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Important

For delegated admin access, you must add the Microsoft Entra application to the AdminAgents group. If the Microsoft Entra application is not added, the consent flow will show an error such as Need pre-consent. For more information, see Pre-consent your app for all your customers in the Graph documentation.

Location

The Business Central administration center API is located at the following URL: https://api.businesscentral.dynamics.com.

Authenticate using service-to-service Microsoft Entra apps (Client Credentials Flow)

Important

This authentication type is supported from version 20.0 an onwards

The Business Central administration center API supports authentication using Microsoft Entra apps.

  1. Sign in to the Azure portal.

  2. Register an application for Business Central administration center in your Microsoft Entra tenant.

    Follow the general guidelines at Register your application with your Microsoft Entra tenant.

    When you add an application to a Microsoft Entra tenant, you must specify the following information:

    Setting Description
    Name Specify a unique name for your application.
    Supported account types Select either Accounts in this organizational directory only (Microsoft only - Single tenant) or Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant).
    Redirect URI Optional. You can grant consent from the Azure portal if left empty.

    When completed, an Overview displays in the portal for the new application.

Note

Copy the Application (client) ID of the registered app. You'll need this later. You can get this value from the Overview page.

  1. Create a client secret for the registered application as follows:

    1. Select Certificates & secrets > New client secret.
    2. Add a description, select a duration, and select Add.

    Note

    Copy the secret's value for use in your client application code. This secret value is never displayed again after you leave this page.

    For the latest guidelines about adding client secrets in Microsoft Entra ID, see Add credentials in the Azure documentation.

    Important

    The sample code below uses a client secret to demonstrate how to obtain an access token. For production scenarios it is not recommended to authenticate using a client secret. Refer to the identity platform security checklist for the latest recommendations on secure authentication using Entra apps.

  2. Grant the registered application AdminCenter.ReadWrite.All permission to the Dynamics 365 Business Central administration center API as follows:

    1. Select API permissions > Add a permission > Microsoft APIs.
    2. Select Dynamics 365 Business Central.
    3. Select Application permissions, select AdminCenter.ReadWrite.All, then select Add permissions.

    Note

    If you intent to use the same Microsoft Entra app with the Automation API and Business Central Web Services you can also grant API.ReadWrite.All and Automation.ReadWrite.All permissions. Learn more here.

  3. (optional) Grant admin consent on each permission by selecting it in the list, then selecting Grant admin consent for <tenant name>. This step isn't required if you'll be granting consent from the Business Central administration center. It is possible to grant consent from this page only for your own current tenant. This works for single-tenant apps, but for multi-tenant apps you have to grant consent for each tenant from that tenant's Microsoft Entra admin center, Azure portal or the Business Central administration center

  4. Go to the Business Central administration center and navigate to the 'Authorized Microsoft Entra apps' page. Paste the Application (client) ID of your app in the form to authorize an app.

  5. If not already completed in step 5 you can grant consent for your app from the 'Authorized Microsoft Entra apps' page in the Business Central administration center.

    Note

    There might be a short delay until the Granted status is visible in the Business Central admin center after refreshing. To grant consent, you must have a Microsoft Entra role assigned that allows for management of application registrations in the tenant, such as the Cloud Application Administrator role. The Dynamics 365 Administrator role that grants access to the Business Central administration center does not allow users to grant consent to applications in the tenant.

  6. (optional) Some operations in the Business Central administration center API require that the app has a permissions assigned in the environment in addition to the authorization in the Business Central administration center. Follow the instructions in Task 2 here to assign permissions.

    Note

    Learn more about permissions required for App Management operations here and learn more about permissions required for Database Exports here.

Getting an Access Token with Client Credentials Flow

HTTP requests sent to the Business Central administration center API must include the Authorization HTTP header, and the value must be an access token.

The following examples show how to obtain such a token using PowerShell. Using C# is straightforward.

PowerShell example without prompt:

$cred = [Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential]::new($AppId, $AppSecret)
$ctx = [Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext]::new("https://login.windows.net/$TenantName")
$token = $ctx.AcquireTokenAsync("996def3d-b36c-4153-8607-a6fd3c01b89f", $cred).GetAwaiter().GetResult().AccessToken

Note

In the PowerShell example above, the guid specified to acquire the token (996def3d-b36c-4153-8607-a6fd3c01b89f) is the resource ID of Business Central. The example gets the client credential using the app secret, but the recommended way would be to rely on X.509 certificates.

Calling Business Central administration center API OAuth2Flows

After the Microsoft Entra application has been set up, authorized in the Business Central administration center, and granted admin consent, you're ready to make API calls.

The following sample uses the Rest Client for Visual Studio Code. Using the Rest Client makes it easy to see which HTTP calls are made both against Business Central and Microsoft Entra ID. Any HTTP client can be used to create the requests below. Or you can choose any library, like MSAL.

@tenantId = <tenant id>
@clientId = <client id>
@clientSecret = <client secret>
@baseUri = https://api.businesscentral.dynamics.com
@scope = {{baseUri}}/.default
@url = {{baseUri}}/admin/v2.15

# @name auth
POST https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token HTTP/1.1
Content-type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={{clientId}}
&client_secret={{clientSecret}}
&scope={{scope}}

### Variable Response
@accessHeader = Bearer {{auth.response.body.$.access_token}}

# @name GetEnvironments
GET {{url}}/applications/BusinessCentral/environments HTTP/1.1
Authorization: {{accessHeader}}

### Variable Response
@environmentName = {{GetEnvironments.response.body.value.[0].name}}

Setting up Microsoft Entra ID based authentication (Authorization Code Flow)

Sign in to the Azure portal to register your client application as an app and enable it to call the Business Central administration center API.

  1. Follow the instructions in the Integrating applications with Microsoft Entra ID article. The next steps elaborate on some of the specific settings you must enable.
  2. Give the application a Name, such as Business Central Web Service Client.
  3. For Application type, choose either Native or Web app/API depending on your scenario. The code examples below assume Native.
  4. Choose a Redirect URI. If it's a Native app, you can choose for example: BusinessCentralWebServiceClient://auth. If it's a Web app/API app, set the value to the actual URL of the web application.
  5. During the registration of the app, make sure to go to Settings, and then under API ACCESS, choose Required permissions. Choose Add, and then under Add API Access, choose Select an API and search for the Dynamics 365 Business Central option. Choose Dynamics 365 Business Central, select Delegated permissions, and then choose the Done button.

    Note

    If Dynamics 365 Business Central doesn't show up in search, it's because the tenant doesn't have any knowledge of Dynamics 365 Business Central. To make it visible, an easy way is to register for a free trial for Dynamics 365 Business Central with a user from the directory.

  6. Make a note of both the Application ID and the Redirect URI. They'll be needed later.

Getting an access token with Authorization Code Flow

HTTP requests sent to the Business Central administration center API must include the Authorization HTTP header, and the value must be an access token.

The following examples show how to obtain such a token using PowerShell. Using C# is straightforward.

PowerShell example without prompt:

$cred = [System.Management.Automation.PSCredential]::new($userName, $secureStringPassword)
$authority = "https://login.microsoftonline.com/$tenantName"
$scopes = [String[]]@("https://api.businesscentral.dynamics.com/.default")
$client = [Microsoft.Identity.Client.PublicClientApplicationBuilder]::Create($applicationId).WithAuthority($authority).Build()
$accessToken = $client.AcquireTokenByUsernamePassword($Scopes, $cred.UserName, $cred.Password).ExecuteAsync().GetAwaiter().GetResult().AccessToken

PowerShell example with prompt:

$authority = "https://login.microsoftonline.com/$tenantName"
$scopes = [String[]]@("https://api.businesscentral.dynamics.com/.default")
$client = [Microsoft.Identity.Client.PublicClientApplicationBuilder]::Create($applicationId).WithAuthority($authority).WithRedirectUri($redirectUri).Build()
$accessToken = $client.AcquireTokenInteractive($scopes).ExecuteAsync().GetAwaiter().GetResult().AccessToken

Error Format

If an error occurs during the execution of an API method, it will respond back with an error object. While the specifics of any error will vary from endpoint to endpoint and by the error, the error object returned should adhere to the following structure. When an error occurs that doesn't fit this structure, it typically indicates that an error occurred in sending the request or during authentication of the request. For example, it could be that the API hasn't yet received the request.

Error Response Object:

{
"code": string, // A stable error code describing the type an nature of the error. Ex: EnvironmentNotFound
"message": string, // A message with a readable description of the error and cause. Intended to assist with debugging or troubleshooting the API, it's not intended to be displayed.
("target": string), // Optional - Provides information about what part of a request caused the error. Ex: The name of a property on the request body.
("extensionData": {...}), // Optional - A key/value dictionary object containing additional information about the error.
("clientError": [ // Optional - A nested list of error objects containing more details about the error encountered. For instance, this may be used if multiple errors are encountered to list them all out.
  {
    "code": string,
    "message": string,
    "target": string,
    "extensionData": {...},
    "clientError": [...]
  })
]
}

General unhandled errors

All unknown and unhandled errors that aren't covered by the lists above will use the error code: Unknown

See also

Manage Apps
Microsoft Dynamics 365 Business Central Server Administration Tool