Low Level API vs High Level API

We are currently in the process of evaluating your product for use in an idP we are creating from the ground up. I have had some serious issues in figuring out exactly which API to use, as we need maximum flexibility to be able to change things on the fly, and from some of the things I’ve scoured the forums for, it seems like the Low Level API provides more flexibility and would also allow us to future proof, as from what it sounds like the High Level API does not play as nicely with the Low Level API.

Could you please advise on a few things:

What situations you think the Low Level API is more worthwhile to use than the High Level API? Or more specifically, when does it make sense to use the Low Level API?

How many of your idP High Level API consumers have had issues and needed to switch to the lower level?

How hard of a transition is that?

The low-level API is the original API. We introduced the high-level API to make SAML integration easier for our customers.
The high-level API is implemented using the low-level API.
Our recommendation is to use the high-level API wherever possible.
It has the following advantages:

  1. It is much easier to use. You don’t have to understand the intricacies of SAML.
  2. It requires less code in your application.
  3. It ensure all the various security checks are performed correctly and removes this responsibility from your application.
  4. It is configuration driven meaning little or no code changes when adding or updating partner providers.
  5. It makes supporting SAML logout much easier.
The low-level API should be used if:
  1. The HTTP-Artifact binding must be supported. However, this is rarely the case.
  2. You require complete control of the SAML SSO process. This is not commonly required but the option is available.
We’re not aware of any customers who started with the high-level API and had to switch to the low-level API.
Using the low-level API means you need a much better understanding of the details of SAML SSO and the SAML specification.
Overall, it requires more effort.