Oauth to connect to the EmbeddApp Business Central. Life story
Recently I was asked by one of the partners to help them to connect external application to the Business Central APIs using OAuth.
"No problem, at all" - thought I, and got into the details. But then I released, that the Business Central they were talking about - is not a standard SaaS environment, but an EmbeddApp environment.
What is an EmbeddApp
For those of you, who does not know what is EmbeddApp program is, you can read details here.
Briefly, it's a program designed for the ISV partners, who have created a very industry specific version of Business Central and want to sell it online. They (partners) are responsible for upgrades, quality and support. Microsoft actually just "hosts" the apps, making them available for the customers.
For us, developers, in most cases this mean - very customisable Base App... and many nuances =)
The first difference we see just from the base url
- Business Central SaaS WebClient:
businesscentral.dynamics.com/
- EmbeddApp Saas WebClient:
[application family].bc.dynamics.com/
What is Application Family
The application family helps identify ISV solution among other Business Central apps and Embed App's of other ISVs.
There is an AdminAPI request to get the list of all available application families
https://api.businesscentral.dynamics.com/admin/v2.7/applications/
So, the EmbeddApp SaaS Web client url could be:
-
Project365.bc.dynamics.com/
-
SerenicNavigator.bc.dynamics.com/
-
SparkRock365.bc.dynamics.com/
-
To-Increase-Food.bc.dynamics.com/
- ...
What about EmbeddApp API url's
Different web client url, means that API base url would also be different.
Instead of BC SaaS API base url: api.businesscentral.dynamics.com
We should use: [application family].api.bc.dynamics.com
Here is the list of all urls to be used with EmbeddApp
So, the EmbeddApp Web APIs base url could be:
-
Project365.api.bc.dynamics.com/
-
SerenicNavigator.api.bc.dynamics.com/
-
SparkRock365.api.bc.dynamics.com/
-
To-Increase-Food.api.bc.dynamics.com/
- ...
What about Oauth for the EmbeddApp APIs
There are a huge amount of blogs about Oauth configuration for the Business Central SaaS, also there is the latest video from the BC Launch Event.
I personally use this blog from AJ https://www.kauffmann.nl/2021/07/06/service-to-service-authentication-in-business-central-18-3-how-to-set-up/
But, i didn't find any blog for the EmbeddApp SaaS. That's actually a reason of this one. After 3 days of experiments I finally got it. And sharing my findings with you.
I will not repeat all steps of the "How to configure OAuth for Business Central", just will give you a differences in configuration, specific for the EmbeddApp
When you create the application in Azure
Follow all the steps described here, but use different Redirect URI
Instead of: https://businesscentral.dynamics.com/OAuthLanding.htm
fill: https://[application-family].bc.dynamics.com/OAuthLanding.htm
Use lower-case, for the application family.
The rest of the configuration will be the same as for the Business Central SaaS Oauth.
When you call EmbeddApp API
So, to access EmbeddApp APIs you should call https://[application-family].api.bc.dynamics.com/v2.0/[environmentName]/api/v2.0
And that's the first place where a Life Story tag in the name of this blog, comes into play.
I got Not Found error
As it appeared after some hours of investigation the APIs were just not installed in the environment!
Technically, Business Central API's are packaged into the extension _Exclude_APIV2_
They are, as a normal extension are dependent on base application. But for the EmbeddApp the base application is different! So the ISV Partner has to provide own version of APIs extension dependent on EmbeddApp, which was not been done in my example.
When you call EmbeddApp Custom API
When I released that there are no APIs available, I thought i should try custom APIs.
Once again, there are huge number of blogs about How to create Custom API for Business Central, it's not a topic of this blog, so i will skip this step.
After I created and published Custom API extension, i tried to call it.
https://{{application-family}}.api.bc.dynamics.com/v2.0/{{environmentName}}/api/{{APIPublisher}}/{{APIGroup}}{{APIVersion}}/companies({{companyId}})/customers
And i got this error:
Takeaways
When you deal with EmbeddApp, always remember that what work on Business Central SaaS, could not work or work differently in EmbeddApp. Especially for this blog:
- Check that APIs are installed
- Check if your OAuth flow is compatible with EmbeddApp Business Central version.
*This post is locked for comments