This is the next blog post in a series about service to service authentication in Business Central. Please see the previous blog posts for more information:
In this post, I want to give some tips on how to test with Postman and Insomnia. Both are tools that are being used by Business Central developers, with most probably Postman the one that is mostly used.
Postman
Setting the access token
The access token must be entered on the Authorization tab of the request. First set Type to OAuth 2.0 and then then you can enter the token under Current Token in the Access Token field. The default setting is to add the token to the request headers with prefix Bearer. Make sure that this setting is not changed.
Retrieving the access token
How to get the token with Postman? A simple way would be to prepare a separate request to retrieve the access token and then copy the token from the response and paste it into the authorization header of the other requests. The response body must be of type x-www-form-urlencoded and contain the same parameters as discussed in the previous blog posts. Here is an example:
Note that the URL of the request uses a variable {{AADTenant}}. This variable is set in the environment variables. Of course, you can also use variables for the values in the request body. As explained in the previous blog posts, AADTenant represents the Azure AD tenant for which you want to access Business Central.
Managing access tokens
But Postman offers a different way of managing OAuth tokens. The OAuth parameters can be specified directly under the Authorization tab of a request. Below the Current Token (where you enter the access token to be used) you will find another tab named Configure New Token. Here you can enter the details to retrieve an access token. Make sure to set the Grant Type to Client Credentials. Optionally you can give the token a name. Below is an example of the Authorization tab with exactly the same parameters as used in the request above.
Postman is not going to automatically retrieve the access token for us. First we need to click on the button Get New Access Token. If the values are correct, then you should get a popup like this:
After this screen closes, a new popup screen is displayed that shows the retrieved access tokens. This screen contains a history of access tokens from which you can select one to use for the request. The example below shows three available access tokens. Expired tokens are displayed as strikethrough. They can be deleted individually or you can use the Delete option in this screen to delete all expired tokens at once. I would recommend that you do that regularly.
By clicking on Use Token you select that token to be used for the request. Back in the request under the Current Token you will also find a dropdown Available Tokens. This can be used to select another token or to open again the manage access tokens window where you can select another token or delete the expired tokens.
Configuring Authorization on a parent level
So far, I’ve only talked about setting the authorization per request. However, that’s not the ideal world. Instead, I would recommend configuring the Authorization on folder or collection level. All requests inside a folder or collection can inherit the authorization settings from their parent. Then you only have to select the current token once on collection or folder level and you can use it for all requests inside the folder or collection until the token has expired. I assume further screenshots are not required to show how to open the collection or folder settings. It’s pretty straightforward.
Insomnia
To be honest, this tool is completely new to me. I’ve got a question from somebody struggling with setting up the client credentials flow with Insomnia. So I decided to install this tool and give it a shot. And because I figured that more people might be using Insomnia, I wanted to include my findings here.
Using Environments
Insomnia also supports environments with variables to be used in the requests. They are basically JSON files and that works pretty easily. Here is an example of a very simple environment settings file.
In the screenshots below I’ve used those variables from the environment to illustrate it.
Setting Authorization
Setting the authorization type on a request is only slightly different from Postman. Just click on the Auth tab. Actually, you need to click twice, first to enable it and then a second time to get the dropdown menu to select the authorization type. Select OAuth 2.0 from the menu.
Select Client Credentials from the Grant Type options. Then fill in the Access Token URL, it should be the same as used in Postman. If you use an environment variable, then make sure to select the correct one. Just click on the variable and select the one you want to use from the popup. Also fill in the Client Id and Client Secret. Then expand the Advanced Options and enter the Scope. Just as a reminder, the scope value is https://api.businesscentral.dynamics.com/.default
I wonder why the scope is under the advanced options. I would expect it to be part of the standard options. It’s easily missed because it’s hidden by default. But for most OAuth flows it’s a mandatory setting. The other settings under the Advanced Options can be left as default.
Retrieving Access Token
One thing that Insomnia does better than Postman is that you don’t have to retrieve the token first. Just hit the Send button and the token will be retrieved automatically if it is not available. This is how the result looks like:
Configuring Authorization on a parent level
It seems that Insomnia does not support configuring the authorization on a parent level, like folders or environments. It’s a requested feature, being discussed here. In the discussion, somebody also mentioned a plug-in that he created for this purpose. See here for more information. I haven’t tried this myself, but if you are an Insomnia user you might want to give it a shot. Please let us know in the comments below if it worked.
Good luck with using Postman or Insomnia! The next post in this series will contain a C# example to use the Client Credentials Flow.