Basic API Authorization with Business Central

You've got a cloud-based Business Central tenancy (or a trial) and you're wanting to use the Business Central API to retrieve core data (Sales Orders, Customers, etc) so you can use it in other apps. And you're also wanting to create webhook subscriptions so that Business Central will notify your infrastructure when certain records are created or changed.

But of course, Microsoft can't allow these APIs to be invoked by any random person on the internet, so you have to pass some security credentials when you use them. This can be a little tricky, and the documentation is poor so let's walk through this.

One way is with Basic Authentication (there is another way, but it's more complex so we'll deal with it later).

For Basic authentication, you use the username with which you log into Business Central and the Web Service key associated with that login.

The Web Service key doesn't automatically exist - you have to create it for a given user. This is a one-time thing. At the time of writing, the easiest way is probably to click the search icon and search for users:

Type in 'users' into the search box - one of the first items that comes up should be a link to the Users list:

You'll see a list of users. Maybe just one user (yourself) if you're experimenting with the Trial version. You'll need to choose one user whose credentials will be used by the web services.

In the User Card that's called up, you'll see a section called Web Service Access.

The web service access key is initially blank so click the Edit Assist button to generate one. I chose an expiration date for the key some time in the future, although you can choose to have it never expire.

Take a copy of this key and store it in a safe place. This 44-character key is the one that you will use in conjunction with your username to authenticate your web service calls.

NB: Clicking the Edit Assist button again doesn't give you access to the key to copy it like you might think. Instead, it gives you a dialog warning that you that you are about to invalidate the key and regenerate it, which may potentially suck for you, depending on how widely you have used that key.

To see that key in its entirety again (i.e. if you want to copy it to your clipboard) you'll have to hit the Expand icon in the top-right corner of the User card (although the key does show as a tooltip if you hover over it).

To test whether your Basic Authentication is working in Postman, call the base API with your tenant ID.

Your tenant ID is the GUID that shows up in the browser address bar when you're interacting with Business Central. For example, I have a trial account at the moment, and the address bar is currently showing

https://businesscentral.dynamics.com/7655266b-06e1-471d-a29a-49c2ae560f11/?company=CRONUS%20UK%20Ltd.&dc=0

That identifier 7655266b-06e1-471d-a29a-49c2ae560f11 is my tenant ID.

Even though we also see a mention of a company 'CRONUS UK Ltd.' in the address bar, the tenant ID is NOT the same as the company ID. You might have several companies under the one tenancy. The companies have different IDs altogether. It's important to recognise the difference between a tenant ID and a Company ID because it comes up a lot when we're formulating REST API requests. We'll have a look at how to retrieve the company IDs in the paragraphs below.

Anyway, back to testing out our Basic Authentication with the tenant Id. For example if the tenant id is 7655266b-06e1-471d-a29a-49c2ae560f11, the base API url will be:

https://api.businesscentral.dynamics.com/v1.0/7655266b-06e1-471d-a29a-49c2ae560f11/api/beta

If you're using Postman to play with the Business Central API, configure it to use Basic Authentication, and specify a username and password. The password is that Web Service Access key that you just set up, and the username is the corresponding Business Central user name:

In fact, a better practice is to use Postman variables:

Postman does a bit of work for you here, by combining and obfuscating the username and password. What Postman really sends out on the wire is an HTTP header:

Authorization: Basic QkMy...{truncated}...ldGOD0=

Basic Authentication is definitely not the gold standard in security. You'd only ever want to send this out over https, as the username and password can be very easily decoded from that Authorization header.

When you hit Send, the call to the base API takes a couple of seconds to return, but you should get a JSON document back containing all the entity types available in Business Central:

{ "@odata.context": "https://api.businesscentral.dynamics.com/v1.0/7655266b-06e1-471d-a29a-49c2ae560f11/api/beta/$metadata", "value": [ { "name": "items", "kind": "EntitySet", "url": "items" }, { "name": "picture", "kind": "EntitySet", "url": "picture" },

...

{ "name": "companies", "kind": "EntitySet", "url": "companies" }, { "name": "subscriptions", "kind": "EntitySet", "url": "subscriptions" } ] }

If you see something like this, then your Basic authentication is working. Let's test it further by sending a GET request to list the companies in your tenancy:

https://api.businesscentral.dynamics.com/v1.0/{{tenantid}}/api/beta/companies

Note that {{tenantid}} is a Postman variable that is substituted with my actual tenant Id. With all these long GUIDs lying around it would be very easy to get them confused. Being able to name them and reuse them across requests is great.

If you're using the same successful Basic Authentication credentials, the above 'companies' URL should return you a JSON document containing basic company information for all the companies in your Business Central tenancy:

{ "@odata.context": "https://api.businesscentral.dynamics.com/v1.0/7655266b-06e1-471d-a29a-49c2ae560f11/api/beta/$metadata#companies", "value": [ { "id": "9f05ad59-8a54-41cd-9f56-63b750f5ad3b", "systemVersion": "28820", "name": "CRONUS UK Ltd.", "displayName": "CRONUS UK Ltd.", "businessProfileId": "" }

... maybe more companies ...

] }

Grab the desired company ID out of this information and save it as a Postman variable (e.g. 'companyid'). It will be handy in the next step.

I embarked on this article when I was particularly interested in creating a webhook subscription to changes in Sales Orders. So let's take that a little further:

We can see in the data returned from the base API URL that we can query a collection called 'subscriptions'. We just append the collection name to the base url:

https://api.businesscentral.dynamics.com/v1.0/{{tenantid}}/api/beta/subscriptions

In my case, I get a JSON document back that tells me I have no subscriptions, as I would expect at this point

Let's pass those same credentials to the REST API call that creates a webhook subscription. The documentation isn't great at the time of writing, it didn't specify the correct URL for the POST operation. I used

https://api.businesscentral.dynamics.com/v1.0/{{tenantid}}/api/beta/subscriptions

Set the Content-Type header to application/json and the body to something like

{ "notificationUrl": "https://myAppService.azurewebsites.net/api/OrderChange", "resource": "/api/beta/companies({{companyid}})/salesOrders", "clientState": "SomeSharedSecretForTheNotificationUrl" }

and POST this. Note the use of the {{companyid}} here in the web service body. You need to be careful that the 'resource' is referencing one of your companies, not your tenancy.

The notificationUrl will be the subject of another article, there is a lot to consider there. But the big picture is this: by the time you create this subscription with the above POST request, you need to have some code in place (e.g. an Azure Function) listening at the notificationUrl location, and it needs to be responding with the validationToken to the query that Business Central will send at the moment you create this subscription.

By this point you should be able to test that the subscription was created by retrieving the list of subscriptions, as we did above. And if your logging permits, you should be able to verify that your notification URL is being invoked as you create and change Sales Orders.