We’re excited to announce the release of SailPoint API v2025, scheduled for 2025-04-01T04:00:00Z! This version introduces some new capabilities and transitions key APIs from experimental to public production status.
We encourage users of our APIs to upgrade to v2025 anywhere they call SailPoint APIs, such as in Workflows, custom scripts and applications, Postman, etc. For more information on SailPoint’s API versioning, including support and deprecation timelines for older versions of our APIs, please see this document:
Experimental APIs
The following APIs have been introduced as experimental.
Machine Accounts
A machine account is a non-human account that relates to an application or service. Machine accounts may include service accounts, bots, or shared accounts that multiple users log in to.
We are committed to rapidly evolving our APIs to deliver stable, reliable, and production-ready endpoints that our customers can depend on. By closely monitoring adoption and feedback, we ensure that experimental APIs mature quickly and meet enterprise-grade standards. The following APIs have successfully transitioned from experimental to public production status:
These APIs implement Suggested Entitlement Description (SED) functionality. SED functionality leverages the power of LLM to generate suggested entitlement descriptions. Refer to GenAI Entitlement Descriptions to learn more about SED in Identity Security Cloud (ISC).
This is great news to read and I’m happy to explore the new v2025 APIs.
Quick question on the versioned APIs (v2024, v2025). A lot of the end points require the X-SailPoint-Experimental header, which (besides being annoying) gives me the impression that you shouldn’t really use the end point. How are you going to handle this header moving forward?
The X-SailPoint-Experimental header is required for any endpoints that can change (including breaking changes) without much notice.
We wanted to make sure that customers know they are using an experimental endpoint and have acknowledged that by providing the header.
We’ve tried to make this as non-interruptive as possible. The SDKs allow you to enable experimental endpoints globally by setting config.experimental = true. I see that the postman collections do not enable the header by default but I will look into correcting that.
I’d like to know more how the header effects you so that we can make it a seamless experience.
Once the endpoint has transitioned from experimental to public production the header is no longer required, but including it won’t hurt anything either.
I understand the requirement from a ‘this endpoint might change so you have to accept using it’. Maybe what I’m missing is some communication on when it is expected to become a public endpoint. And in addition how that relates to the version. I see a lot of experimental endpoints in the v2024, while I would expect (with 2024 being gone) that any API under v2024 would no longer be experimental, i.e. v2024 would not undergo any (breaking) changes.
Our goal is for endpoints to transition from experimental to public production after 6 months. With that being said we can continue to improve on communicating when endpoints transition.
How would you like to be notified of changes to endpoints? Some ideas I’ve thought about:
A forum category with topics for each API transitioning
Some kind of email notification that can be subscribed to
Experimental endpoints that were in v2024 will stay experimental in both v2024 and v2025. When they transition to public, both versions will be update to public.
Ok, that is clear, roughly 6 months after an endpoint is added (and as such made experimental) we should expect it to become public. Then I would suggest we have the following:
For each endpoint a mention of when the endpoint is brought live and when we can expect it to become public
On the developer API documentation a change log / release notes, perhaps even a roadmap. That way you can track what was made available and what is upcoming. You should be able to subscribe to this page.
In addition maybe some more clarity on the release schedule or even an update if things change.
If I read that image then the v2025 release with ‘breaking changes’ should have been available in the second half of calendar year 2024. Perhaps that was not possible yet, but if not that should be updated and communicated as well.
If I’m misinterpreting that, then that is my fault, but perhaps the documentation is then also not clear enough?
Another thing I noticed in the documentation is this:
Communications will be sent out to notify impacted users of any deprecations. These communications may appear in the Admin page of the Identity Security Cloud UI, in the Announcements category, in Compass, or in newsletters or emails.
That seems to me very much, please look yourself at different places where our communication is. Especially with these types of changes, I would love to have one single place to find it all, without me having to look through my emails, compass or the forum to find what I’m looking for.
I will work with our teams and see what we can come up with for a single source of truth.
I will update this documentation to make it more clear. What this is meant to convey is that if any public APIs need to have breaking changes the next years version will be used such that we don’t include a breaking change in the current public production version.
For example, lets say we introduced a breaking change in the next month on /v2025/access-profiles we would introduce v2026 early and introduce any breaking changes to /v2026/access-profiles as experimental.
