Introducing SailPoint API v2025

Announcements Product News
, ,
1

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.

Machine Identities

Public Production APIs

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:

Access Request Identity Metrics

Tenant

MFA Configuration

Configure and test multifactor authentication (MFA) methods.

Suggested Entitlement Description

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).

SP Config

Import and export configuration for some objects between tenants.

Custom Forms

These APIs build and manage custom forms. With this functionality in place, administrators can create and view form definitions and form instances.

Rollout Schedule

2025-04-01T07:00:00Z

2025-04-02T07:00:00Z

  • Production Low Risk

2025-04-03T07:00:00Z

  • Production Med Risk

2025-04-04T07:00:00Z

  • Production High Risk
5 Likes
2

Great news but we will need the documentation of it.
All the links are still referencing to v2024!

3

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?

1 Like
4

Yes, you are correct. The changes will be live on developer.sailpoint.com on April 1st. I’ll update the links here once it is live.

5

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.

6

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.

7

Understood.

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
  • An API change log on developer.sailpoint.com

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.

8

Good News release of SailPoint API v2025

9

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.

image
image1920×768 63.3 KB

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.

1 Like
10

All good points.

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.

11

That makes sense to me, but indeed was not clear from the docs. So any change in wording / examples given to make this more clear would be greatly appreciated. For now at least I know what to expect.

12

@OlivierJacques,

developer.sailpoint.com has been updated with the new version and I’ve updated the links here in the topic!

13

Thank you Tyler. As you already know, no docs = no feature

14

Great stuff @tyler_mairose, I am excited to check it out, but I stumble upon some hurdles.

I called API’s like GET /v2024/personal-access-tokens from Bruno (similar to Postman) and got 200 OK message with results.

I then only changed v2024 into v2025, and then got a 400 Bad Request message with error “Invalid route”.

I noticed the same with /v2025/roles, /v2025/access-profiles, and others.

The documentation mentions these APIs exist. For example: list-access-profiles | SailPoint Developer Community.

Do you observe the same issue in your personal tenant @tyler_mairose?
Note that it is working in non-production, but for production it is failing. Does production have a different release date? If so, when will that be?

On another note, I saw that the now production API GET /v2025/form-definitions does have fields offset and limit, but does not have the field count. Because of this, we can not use our standard script that paginates over the objects by calling the first page with count=true, to then calculate how many pages are needed and then call all these pages with count=false, to meet with the suggestion of SailPoint here to not use count when not needed. Standard Collection Parameters | SailPoint Developer Community. Do you know if this attribute was omitted on purpose, or if it was perhaps forgotten to add it?

I agree with the usefulness of having release notes on API documentation, such that we know when APIs are created/updated/deprecated instantly. On top of that I would like to suggest a thread per experimental API, where we could discuss the API, give our feedback and suggest improvements before it turns into a production API. In there I could for example suggest adding count to be consistent to all other list APIs that SailPoint has.

Similar improvement suggestion would be GET /v2024/personal-access-tokens missing pagination logic at all, which will get issues if too many personal access tokens are defined.

Kind regards,
Angelo

15

@angelo_mekenkamp,

I apologize I missed adding the release schedule to the announcement. I will make sure that is added initially in the future. The final rollout will be tomorrow morning, if you still don’t see the v2025 apis active please do let us know.

This was likely just a miss on our part, if the endpoint supports it, we will get it documented.

These are good points. I will work with the team to see if we can get topics up for experimental endpoints.

I will check on this one as well.

16

Hi @tyler_mairose, were you able to check those out?

In addition I have made some more observations I would like to share.

  1. GET /v2025/access-request-administration exists, requires experimental header, and we are authorized to call it with our Personal Access Tokens depending on scope, but this endpoint is not documented. Note that there might be even more available endpoints for this module access-request-administration that are undocumented.
  2. same for GET /v2025/authorization-capabilities.
  3. same for GET /v2025/launchers.
  4. same for GET /v2025/roles/identity/{{identityId}}/roles.
  5. same for GET /v2025/system-notification-config.
  6. same for POST /v2025/sources/{{sourceId}}/load-entitlements
  7. The APIs for GET /v2025/entitlements are marked as experimental, but this object type entitlement already exist for years and these APIs are already in beta or now in experimental state for years. Is it on the roadmap to have public APIs for management of this long existing object type?
  8. same for /v2025/entitlements.
  9. same for /v2025/workgroups (these are actually governance groups).
  10. same for /v2025/identities.
  11. same for /v2025/identity-attributes.

Kind regards,
Angelo