Upcoming Changes to the SailPoint API Versioning Strategy
We are planning a significant update to how SailPoint’s Identity Security Cloud APIs are versioned based on your feedback. This document outlines what is changing, why we are making these changes, and what they mean for you as an API consumer or integration developer.
This is an additive change, you are NOT expected to migrate immediately. Though it is recommended to get the benefits of the new changes.
Post your questions directly in the thread below!
What Is Changing
SailPoint is moving away from a shared annual release model (e.g., v2024, v2025, v2026) toward true semantic versioning at the individual service level.
Under the new strategy, each API service will be versioned independently. A new major version of a service will only be introduced when that service’s usage contract actually changes, not because a new calendar year has arrived. The URL structure will follow a pattern like:
/accounts/v1
/identities/v2
/roles/v1
This gives customers a stable, predictable target. As long as a service’s contract is unchanged, your integration continues to work, indefinitely.
When a breaking change is genuinely required, a new version (e.g., v2) will be developed and released in parallel with the existing version, and the older version will enter a clearly defined deprecation schedule on its own timeline.
Why We Are Making This Change
The current annual versioning model has introduced a number of pain points for both customers and internal teams. The key issues driving this change are:
Customers Are Forced to Update Integrations Even When Nothing Changed
Under the current model, all APIs are rolled into a new version each year, regardless of whether any breaking changes were made to a particular service. This means a customer targeting v2024 may be required to update their integration paths or SDK method calls to v2026 even if the underlying service they use has not changed at all. There is no clear signal that a new yearly version contains meaningful differences for their specific use case.
With per-service versioning, a customer using /transforms/v1 will not need to change anything until SailPoint actually introduces a breaking change to the Transforms service and releases /transforms/v2.
NOTE: API routes can be versioned independently for example, POST
/transforms/v2could be created with a breaking change on how transforms are created but GET/transforms/v1to list the transforms would remain unchanged.
New APIs Are Constrained to an Annual Window
If a service is not ready to ship by the cutoff for a given year’s release, it must wait for the next annual cycle. This delays meaningful improvements and limits teams’ ability to ship when they are ready.
With per-service versioning, any service can introduce a new version as soon as it is ready, independent of every other service.
The /latest Endpoint Is Unstable for Production Use
The current /latest alias was introduced to help reduce churn from yearly version changes, but it is inherently unsafe for production integrations. If a breaking change is introduced to any service, a customer using /latest can have their integration break without warning. The existence of /latest as a workaround signals that the annual versioning model is not meeting customer needs on its own.
If you are currently using /latest, we recommend migrating to an explicit versioned path before the legacy APIs are deprecated in Q1 of 2029. When you write your integration the most recent version available is essentially the same as using latest as it will only change if there is a breaking change.
Maintaining Multiple Year-Based Versions Is Expensive and Error-Prone
Each annual release requires duplicating the entire API collection. This process takes significant engineering time and frequently results in inconsistencies, mismatched descriptions, outdated examples, experimental headers that linger past their intended lifespan, and other documentation drift. Customers occasionally encounter an experimental API in v2025 and have no clear way to know whether the same API is stable in v2024 without manually navigating to the prior year’s documentation.
With independent service versioning, each service is documented once and updated in place. There is no duplication, and the experimental/stable boundary is clearer within a single service’s version history.
What Is Staying the Same
- The distinction between public (production-ready) and experimental APIs remains. Experimental APIs may still introduce breaking changes and require an opt-in header.
- The definition of breaking vs. non-breaking changes does not change.
- The definition of breaking vs. non-breaking changes does not change.
- Deprecated APIs will continue to remain operational for a defined transition window before being turned off, and deprecations will still be communicated through announcements, API specification notices, and response headers.
What This Means for You
| Scenario | Under Current Strategy | Under New Strategy |
|---|---|---|
| A service you use has no changes this year | You still need to update your integration path to the new year’s version when the old one is deprecated | Your integration path stays the same until a breaking change is actually introduced |
| A breaking change is introduced to one service | All services receive a new year-based version | Only the affected service receives a new major version |
| You want to run v1 and v2 of the same service concurrently | Not supported within the same year namespace | Supported — both versions are accessible simultaneously |
| An experimental API you rely on graduates to public | You need to find the stable version in the appropriate year’s docs | The same service URL path moves to public status; the prior year lookup is not needed |
Legacy APIs
Moving forward, Beta, V3 and the yearly versioned APIs (v202X) will be deprecated in favor of the new versioning process. Beta, V3 and the Yearly versions will be supported until Q2 of 2028, meaning that users can submit support tickets for these versions. After Q2 of 2028, users may no longer submit support tickets for these versions and will be asked to migrate to a supported version instead. These legacy endpoints will be end-of-life and no longer function Q1 of 2029.
Changes to developer.sailpoint.com API documentation
The documentation will flatten to just one collection, no more version dropdown.
How will I know if there is a new version of an endpoint or service?
When a new version of an endpoint is released it will have a badge next to the API corresponding to the version.
The initial
v1APIs have no badge. This will just be for new versionsv2and greater.
Changes to Postman Collections
The biggest change to the postman collections is that there will just be one single collection. You will not have to maintain and stay up to date with multiple collections across yearly versions.
Your existing environments remain unchanged, the pre-script to obtain a token for you works without modification. The underlying API routes in the collection itself are changed to support the new versioning, but how you are used to it functioning does not.
Changes to the SDKs
The SDKs will be updated with a major release and method signatures changed. The details of these changes will be introduced with the SDK changes themselves.
One benefit is that this allows for some structural changes within the SDKs allowing you to only bring in the methods important to you instead of loading in the whole SDK.
Migration Guidance
A full migration guide — including updated SDK documentation, Postman collection changes, and path mapping from the current year-based versions to the new per-service versions will be available shortly after the production release.
SailPoint will provide migration scripts to reduce the manual effort required.
If you have question when migrating to the newer service level versions please ask your questions in Identity Security Cloud (ISC) > ISC Discussion and Questions and tag it with api-versioning
Timeline
Roll out plan
Staging - 2026-06-22T14:00:00Z
- New
service/v1service/v2routes callable
Production - 2026-06-24T14:00:00Z
- New
service/v1service/v2routes callable - Changes to developer.sailpoint.com to support new versioning
- Updated Postman collections
SDK Updates - 2026-07-01T14:00:00Z
- Migration Docs and Scripts
