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:

You do not have access to this object using an application as authentication.

That was really fun to understand what was really going wrong. At some point of time, i released that the the EmbeddApp version of BC i was using is 18.1.

May be you already have guessed. If not, here is another hint - I was using client credentials flow or in another words service-service communication. 

Still did not guess? Well, service-service communication is supported only after Business Central version 18.3!

When I changed to the password credentials flow (with user name and Password) i could access Custom APIs for the EmbeddApp without any problems

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.