A Discussion of SailPoint's API Versioning Strategy

Identity Security Cloud (ISC) ISC Discussion and Questions
, , , ,
1

Click here to fill out a survey on this proposal

1. Overview & Purpose

SailPoint is evaluating a significant change to how its Identity Security Cloud (ISC) REST APIs are versioned. The current annual release model has served as a foundational structure, but as our platform and community have grown, several meaningful pain points have emerged — both for our own development teams and for the customers and partners who build on our APIs every day.

This post presents the current strategy, outlines the specific problems it creates, proposes a new approach based on per-service semantic versioning, and describes two concrete migration paths for reaching that new state. We are sharing this publicly before making any decisions because this change directly impacts how you build, maintain, and evolve your integrations with SailPoint. Your feedback will directly shape the final direction.

We ask that all feedback be submitted via the survey linked at the top and bottom of this post no later than May 18th.

2. Current Versioning Strategy

Full reference: API Versioning Strategy

2.1 How It Works Today

SailPoint’s current API versioning strategy uses an annual release model.

Each year, a new versioned collection of all API endpoints is published under a year-based namespace (e.g., /v2024, /v2025, /v2026). All services — whether or not they have changed — are carried forward into the new version collection.

The current URL structure is:

https://{tenant}.api.identitynow.com/{version}/{service}/{action}

# Example:
https://acme.api.identitynow.com/v2026/accounts

Versions currently available: v3, beta, v2024, v2025, v2026.

2.2 Public vs. Experimental APIs

  • Public APIs are production-ready. They generally do not receive breaking changes. Non-breaking additions (new optional fields, new endpoints, new enum values, etc.) may be introduced at any time within the same version.
  • Experimental APIs are under active development. They require the X-SailPoint-Experimental: true request header and may change with little or no notice. When an experimental API is deemed production-ready, it is promoted to public in the current year’s release.

2.3 Release Schedule

A new annual release is published each calendar year. If a new release contains breaking changes, those changes are first introduced as experimental APIs in the following year’s version. Non-deprecated endpoints from the previous version are carried forward unchanged.

Annual versions are supported for 3 years, then remain operational for an additional 2-year transition period, after which they may be decommissioned.

2.4 Deprecations

Deprecated APIs are announced through:

  • In-product Admin UI notifications
  • Developer community announcements
  • API specification deprecation markers
  • The X-Deprecated: true response header

Individual APIs may be deprecated at any time and will remain functional for two years following their deprecation notice.

2.5 The /latest Endpoint

The /latest endpoint was introduced in response to community feedback to allow integrations to automatically route to the most recent public version of an endpoint, without requiring a hardcoded version string. It is intended for development, testing, and non-critical integrations only. Production integrations should always target an explicit version.

3. Identified Problems

The following problems have been identified through our platform’s evolution and external community feedback. They are grouped by impact.

3.1 Problems Impacting Customers & Partners

Forced churn with no functional change

When a new annual version is released, customers must update their integration paths (e.g., /v2024/accounts → /v2026/accounts) even when the underlying API contract has not changed at all. There is no clear signal to developers that a given endpoint in a new version is meaningfully different from the prior year — only that a year has passed. This creates recurring maintenance work with no tangible benefit.

Example: An integration targeting /v2024/accounts that has not needed to change anything will still be forced to update paths or SDKs when v2024 is deprecated, even if /v2026/accounts is functionally identical.
Severity: High

No concurrent access to old and new versions of the same service

Under the current model, you cannot simultaneously use v2024/accounts and v2025/accounts in a meaningful way that reflects an intentional migration strategy. Year-based collections couple all services together, making it impossible to adopt a new version of one service while keeping an older version of another.

Example: If an accounts integration depends on a v2024 behavior, but you want to adopt the v2025 identities endpoint, you are coupled into the same version namespace regardless of readiness.
Severity: Medium

Experimental status ambiguity across versions

When an API is marked experimental in v2025, developers must navigate back to v2024 to determine whether the same endpoint is stable in the prior version. The version-per-year structure adds a layer of indirection that makes it hard to understand the lifecycle state of any given endpoint without cross-referencing multiple collections.

Severity: Medium

The /latest endpoint is inherently risky for production

The existence of /latest reflects a real need — nobody wants to update version strings every year when nothing has changed. But /latest solves the wrong problem: it trades forced manual updates for automatic silent changes, which is equally problematic in production environments.

Example: An integration using /latest/accounts may see unexpected behavior when a new annual version is released that contains subtle behavioral changes, with no advance warning.
Severity: High

4. Proposed New Strategy

4.1 Core Concept: Per-Service Semantic Versioning

The proposed strategy replaces the shared annual release model with independent semantic versioning at the service level. Each service owns its version number. A service’s major version only increments when its usage contract changes — not because a calendar year has turned.

The proposed URL structure is:

https://{tenant}.api.identitynow.com/{service}/{version}/{action}

# Examples:
https://acme.api.identitynow.com/accounts/v1
https://acme.api.identitynow.com/identities/v3

4.2 How This Changes the Model

Concern Current Model Proposed Model
Version scope Entire API collection Per service
Version trigger Annual calendar Breaking change in that service
URL structure /{year-version}/{service} /{service}/{version}
New version release window Once per year Any time a service is ready
Unchanged services Carried forward into new collection Untouched — no update required
Concurrent old/new access Not possible within same collection Natively supported
Deprecation timing Tied to release cycle Set independently per service

4.3 Public vs. Experimental

The existing Public/Experimental distinction is preserved under the new model. The X-SailPoint-Experimental header continues to gate experimental endpoints. The key difference is that a service’s experimental endpoint can graduate to public on its own timeline, without waiting for an annual release.

4.4 Deprecation Under the New Model

When a breaking change is introduced to a service, the old version enters a clearly defined and publicly communicated deprecation window specific to that service. Both the old and new versions remain accessible concurrently during that window. Customers decide their own migration timeline within the deprecation period.

4.5 What This Solves

  • No more forced churn. If you’re on /accounts/v1 and nothing has changed, your integration never needs to update.
  • Concurrent access. Developers can run /accounts/v2 and /identities/v1 side by side, migrating service by service on their own schedule.
  • Release flexibility. Service capabilities ship when ready, not when the calendar says so.
  • Clearer lifecycle. Version numbers communicate meaning — v2 of a service explicitly signals a different contract, not just a different year.
  • Simplified documentation and OpenAPI specs. Each service is documented once and updated in place, rather than duplicated per release year.
  • Eliminated duplication. No full collection copy required. Only changed services produce new artifacts.
  • Better API Documentation, SDKs, Logs, and Telemetry. This structure would streamline our API Documentation, allow for SDKs to be generated and versioned per service, making individual updates and package versions reflect the underlying service changes instead of “a new release was made”.

5. Migration Options

Two migration paths have been identified for transitioning existing APIs from the current annual versioning model to the new per-service model. In both cases:

  • The legacy collections (V3, Beta, v2024, v2025, v2026) are deprecated on a communicated timeline and retired.
  • No new year-based collections are ever created.
  • The existing collection is modified in place — new versioned endpoints are added as new services are introduced or updated.
  • Only services with breaking changes receive a new version number.

Option 1 — Universal v1 Reset

All services are migrated to a /v1 endpoint regardless of their historical version number.

When the migration is complete, every service starts at v1. When a breaking change is later required for a given service, that service moves to v2. All other services remain at v1 indefinitely until they also require a breaking change.

# Initial state:
/accounts/v1
/identities/v1

# After a breaking change to Accounts:
/accounts/v1    ← deprecated, still accessible
/accounts/v2    ← new version
/identities/v1  ← unchanged

Advantages

  • Maximum consistency. All services start from the same baseline. Documentation, SDKs, and tooling are uniform from day one.
  • Simple consumer mental model. Developers always know where to find the initial version of any service.
  • Straightforward implementation. Migration logic is identical for every service.

Disadvantages

  • Semantically inaccurate. Services like /identities have meaningful version history — calling them v1 implies they are brand new when they are not.
  • Loses historical context. External consumers who understand the maturity curve of a service lose that signal.
  • Potential for consumer confusion during migration: an integration engineer who knows they are on v2024/accounts (which was a mature API) may be surprised to find /accounts/v1.

Suitable if…

  • A clean break and fresh start is the priority.
  • Platform consistency and operational simplicity outweigh historical accuracy.
  • The communication plan around the migration can adequately address expectations around maturity signaling.

Option 2 — Preserve Existing Service Versions

Each service is migrated to a new endpoint that reflects its actual current version number. A service’s historical version is determined by its true underlying implementation version, not its year-based alias.

When the migration is complete, services land at their real versions (e.g., Accounts at v4, Identities at v3). When a breaking change is required, that service simply increments from wherever it currently stands.

# Initial state:
/accounts/v4
/identities/v3

# After a breaking change to Accounts:
/accounts/v4    ← deprecated, still accessible
/accounts/v5    ← new version
/identities/v3  ← unchanged

Advantages

  • Semantically accurate. Version numbers reflect the real maturity and history of each service.
  • Preserves continuity for experienced consumers. Partners and customers who are familiar with specific service versions can map their existing knowledge to the new structure.
  • Honest versioning. A service that has existed for years and gone through multiple breaking changes carries that history forward rather than erasing it.

Disadvantages

  • Inconsistency at launch. Services will be at different version numbers from day one, which can appear disorganized to new developers encountering the API for the first time.
  • More complex migration mapping. The translation from current year-based versions to true service versions requires per-service analysis and clear documentation.
  • Documentation overhead. Each service’s version lineage must be clearly communicated to help consumers understand what the version number means relative to the legacy year-based collections.

Suitable if…

  • Semantic accuracy and historical continuity are valued over a clean slate.
  • The developer base is experienced and familiar with SailPoint’s current API surface.
  • The migration documentation can adequately explain the version mapping from old to new.

6. Impact Summary

Stakeholder Current Experience Experience Under New Strategy
Integration developers Update paths annually regardless of changes Paths are stable until a breaking change in that specific service
Partners building on SDKs Wholesale SDK updates each year Surgical updates only when a service they use changes
API/Platform teams Wait for annual window, copy entire collection Ship when ready, update only the service spec
Documentation team Duplicate and maintain all docs per year Maintain docs per service, in place
New API consumers Navigate year-based namespaces to find latest Find a service by name, version signals contract maturity

7. Open Questions

The following questions remain open and are part of what we are seeking community input on:

  1. Version number starting point. Should all services reset to v1 (Option 1), or should they reflect their actual historical versions (Option 2)?
  2. Migration timeline. How long should the legacy year-based collections remain accessible alongside the new per-service endpoints? What is a reasonable transition window?
  3. SDK impact. How would per-service versioning affect how you consume or generate SDKs? Would per-service SDK modules be preferable to a monolithic SDK?
  4. Deprecation notice period. Under per-service versioning, how much advance notice do you need before a version is deprecated?

8. Community Survey

We ask that all feedback be submitted via the survey linked at the top and bottom of this post no later than May 18th.

We strongly encourage all responses to be submitted before the deadline, as all feedback will be reviewed together and inform the final proposal.

Thank you for taking the time to read through this proposal. We care deeply about the experience we provide, and we want to hear from you on how you feel about the versioning strategy we have laid out here.

The questions on the survey are designed to help us understand your experience with the current versioning strategy and your preferences and concerns about the proposed changes.

Please answer as thoroughly as you are comfortable with — specific examples and context are extremely valuable to us.

Click here to fill out a survey on this proposal

Introducing SailPoint API v2026