Business Central comes with a set of API’s that you can access from other applications. When running BC in Azure you can choose between basic authentication and Oath 2.0. The latter is preferable since the requesting app does not need to store user name and password. The user will input these when giving consent for the app to access the BC API’s. The problem with Oath 2.0 is that you receive a token for access that expires.
Using basic authentication you store a user name and a web access key in the requesting app and does not have to deale with expiring tokens. Basic authentication does work in production even thoug Microsoft says that Oath shall/should (they actually say both in the same document) be used in production.
First we take a look at AAD authentication/Oath and how to set that up. The main tasks are:
- Create an app in Azure AD
- Get the Access Token in Postman
- Use the Access Token in Postman to access the API
1. Create the App in Azure AD
The AAD App act’s like a contract between the BC API and the requesting app.
- Login to Azure Active Directory
- Select App Registrations
- Click “New registration”
- In “Register an application”:
- Give the app a name
- Select from where your app is supposed to be accessed in “Supported Account Types”
- Set “https://businesscentral.dynamics.com” as redirect URL
- Click on “Register” to create the app.
- Click on “Certificates & Secrets”
- Click on “New Client Secret”
- In “Add a client secret”:
- Select if and when the client secret expires
- Copy the secret and save it. You will need this in Postman.
- Click on “API permissions”
- Click on “Add a permission”
- In “Request API permissions”:
- Click on “Dynamics 365 Business Central”
- Click on “Delegated permissions”
- Select “user_impersonation”
- Click on “Add permissions” in the bottom of the page
- Back in “API permissions”:
- Click on “Grant admin consent for <organization name>”
- Click on “Yes” to confirm.
- Click on “Overview” and copy the “Application (client) ID”. You will need this in Postman.
2. Get the Access Token in Postman
In this step you will create a collection in Postman and request an access token that is used in the requests you create in the collection.
- Create a new collection in Postman
- Give the collection a name and select the Authorization tab
- Select Type = Oauth 2.0
- Click on “Get New Access Token”
- Fill in the following:
- A Token Name
- “Grant Type” = “Authorization Code”
- “Callback URL” = “https://businesscentral.dynamics.com/”
- “Auth URL” = “https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize”
- “Access Token URL” = “https://login.microsoftonline.com/organizations/oauth2/v2.0/token”
- “Client ID” = <your client ID>
- “Client Secret” = <your client secret>
- “Scope” = “https://api.businesscentral.dynamics.com/user_impersonation”
- Click on “Request Token”
- Authenticate with a valid user and password.
- Click on “Use Token”
- Click on “Create” to create the collection
3. Access the API
In this step we will create requests in the collection. The requests will inheret the authorization from the collection. Our aim is to retrieve a list of customers.
My example is based on the environment “sandbox”. Change that to whatever environment you want to access (e.g. “production”).
- Expand the collection in the list of collections
- Create a request to list companies in the BC database
- Click on “Add requests” or the three dots at the right and select “Add request”
- Give the request a name (e.g. “Companies”)
- Click on “Save to <your collection name>”
- Select the request in the left pane
- Type in “https://api.businesscentral.dynamics.com/v2.0/sandbox/api/v1.0/companies” as the URL
- Click on “Send” and you should get a list of companies.
- Copy the id of one of your companies. You will need it in the next step
- Click on “Save” to save the request
- Create another request
- Give the request the name “Customers”
- Click on “Save to <your collection name>”
- Type in https://api.businesscentral.dynamics.com/v2.0/sandbox/api/v1.0/companies(<your company id>)/customers
- Click on “Send” and you should get a list of customers
Did you make it all the way down here? Good job!
What about using basic authentication? Well, that’s much easier. There’s no need to mess around in AAD.
- Create a user in BC with a web access key
- Create a collection in Postman with basic authentication. The username shall not include the domain name
- Create a request to list your companies. The URL now follows this syntax: https://api.businesscentral.dynamics.com/v2.0/<domain>/<environment>/api/v1.0/companies
Basic was a bit easier 🙂 But is it supported by Microsoft in the long run? I don’t know.