Deprecation: Non-Public API Deprecations (CC, V2)

Announcements Product News
, ,
1

The official list of deprecated APIs has been released in a new category called API Deprecations. Please read this guide for more information on how the category works and how to provide feedback.

General Guidance for the use of SailPoint APIs

This announcement is to provide our Customers and Developer Community with appropriate expectations and guidance on the development and deprecation lifecycle of SailPoint’s Public APIs. Also included is information on the upcoming deprecation of SailPoint’s legacy Non-Public APIs, general details on which APIs are to be deprecated, end-of-life (EOL) timelines, and how to stay informed on additional upcoming information around this effort.

API Definitions

How to determine which category an API falls into for the purpose of this announcement:

  • /api → Non-Public APIs (ex. /cc/api, /api, /api/v2)
  • /v2 → Non-Public APIs
  • /beta → Public Beta APIs
  • /v3 → Public Production APIs

Notice of Deprecation for Non-Public APIs

SailPoint will be required to deprecate and end-of-life legacy, Non-Public APIs. Any API that does not start with /v3 or /beta is considered a legacy, Non-Public API.

SailPoint’s legacy, Non-Public IdentityNow APIs were originally designed for internal use by SailPoint and were not designed for external use. Because of this, these APIs do not include many of the features or requirements that exist in our Public API specifications to safeguard misuse and protect large scale performance. As SailPoint continues to upgrade and modernize our event-driven SaaS architecture, many of the microservices that manage these legacy Non-Public APIs are being replaced with new services that adhere to our Public API specifications.

We realize that many of our customers may have built custom processes which call these Non-Public APIs. It is our intent to provide customers with as much notice as and information as possible to provide customers adequate time to redirect any processes calling Non-Public APIs to use our Public APIs instead. In some cases, we will not be able to offer the standard 12 month period between deprecation announcement and final EOL. Please see the FAQ below for additional details.

Guidance for Public Beta APIs

In response to the growing number of Beta API endpoints in our API landscape, SailPoint is making improvements to the overall lifecycle of Beta APIs. Beta APIs can be identified as any API that begins with /beta.

As an immediate measure, we will be reviewing all Beta APIs and promoting the endpoints that we determine to be stable to v3. Any Beta endpoint that is promoted to v3 will remain in Beta for backwards compatibility. Please watch for announcements in the Developer forum for updates on Beta API promotions. If you are using a Beta API that has a v3 equivalent, we encourage you to update to the v3 endpoint as soon as you can.

More details about our plans for beta APIs will be announced in the coming months.

Guidance for Public Production Version APIs

There are no changes to be announced at this time for SailPoint Public Production Version APIs. Below are a few points for general guidance.

  • Public Production Version APIs are any API that starts with /v3 or above.
  • No breaking changes will be introduced to public Production Version APIs.
  • When a supported, public Production Version API is deprecated, it will remain accessible for an additional 12 months after deprecation is announced. After 12 months, it may be removed at any time.

FAQ

  1. Why is SailPoint deprecating APIs?
    Deprecating outdated APIs helps SailPoint maintain the quality and security of our platforms by removing or replacing outdated functionality with more modern and performant solutions. Effective API deprecation practices provide users with consistent behavior expectations, help maintain a healthy API ecosystem, promote innovation, and encourage the development of new and better APIs. By providing these guidelines, we want to ensure our Developer Community is aware of any coming changes, can plan accordingly to minimize disruption, and can make the most of the extensibility of our products and services.

  2. What does SailPoint mean by “deprecating” an API?
    Deprecation means to mark a component of software as obsolete so that it may be phased out at a later time. Generally speaking, any update to an API that removes or changes existing endpoints, schemas, response codes, parameters, or behavior can potentially break a user integration and should therefore follow this deprecation guide. Announced deprecation of an API starts the clock for its EOL (End of Life) date. SailPoint’s Public APIs have a 12 month EOL period to allow users to plan and implement changes accordingly. It is our intent to honor the same 12 month period for Non-Public APIs but depending on the reason for deprecation, a shorter timeline may be required in some cases. The posted deprecation details for each API will include the EOL date and the replacement APIs for that service, if applicable.

  3. How do I know which APIs are Non-Public APIs?
    Today, any API that does not start with /v3 or /beta is considered a legacy, Non-Public API. These Non-Public APIs usually start with either /cc or /v2 .

  4. What is the timeline for deprecating SailPoint’s Non-Public APIs?
    All Non-Public APIs (any API that does not start with /v3 or /beta) are planned to be deprecated over the next 2 years. SailPoint APIs that start with /cc are the highest priority and must be EOL by 12/31/2023. SailPoint APIs that start with /v2 do not have the same urgency and will follow the 12-month EOL period from their individual deprecation announcement. The official deprecation announcement for each API will be posted on this site as soon as the replacement API can be made public.

  5. Where can I find a list of all Non-Public APIs to be deprecated?
    An announcement will be posted on developer.sailpoint.com/discuss that will serve as the main list for all Non-Public APIs to be deprecated. (Note, this announcement does not exist yet, but will be linked here once it is created.) It will include the endpoint being deprecated, the EOL date when it will no longer be available, and a link to the specification for the new Public API that will replace it, if applicable. The announcement will be updated as additional Non-Public APIs are targeted for deprecation. Developer Community Members are encouraged to subscribe to this announcement to receive notifications when it is updated.

  6. How do I know if I am affected?
    We highly encourage customers to review all direct API calls, scripts, custom code, or other tools you may have in use. Scan these for APIs that start with /cc or /v2 and begin planning accordingly to update these utilities as needed to minimize disruption. An announcement will be posted on developer.sailpoint.com/discuss that will serve as the main list for all Non-Public APIs to be deprecated, EOL timelines for each API, and the updated Public API that can be used in its place, if applicable.

  7. Will all Non-Public APIs being deprecated have a Public API equivalent?
    The most common APIs will have an equivalent Public API provided as a replacement. In a few cases where Non-Public APIs are rarely used or present security/performance issues, we reserve the right to not provide an equivalent Public API.

  8. How can I stay up to date on new information around the deprecation of Non-Public APIs?
    Subscribe to this announcement. Additional updates and changes will be mentioned here. Additionally, subscribe to the announcement that will serve as the main list of Non-Public APIs to be deprecated, when it becomes available. It will be posted soon and linked back to this announcement.

Please, post your questions to this thread and we will answer there as quickly as possible. We will also use these questions and answers to improve the FAQ provided above. If you have additional questions, please direct those to your CSM and we will work with you get them answered. Thank you, as always, for your continued partnership!

10 Likes
2

What about the v2/workgroups API call to create a governance group? There is no adequate call in the beta or v3 API. Will this be integrated in the beta API?

5 Likes
3

We are looking for v3 apis which can provision/deprovision idn permissions(report admin, role admin, full admi,etc) to Identities.
As of now we are using cc apis for this.

4 Likes
4

First, I’m not sure that all “Non-Public” API calls are available on V3 or Beta API call… Why ?

Next, why the update should impact client and why Sailpoint doesn’t do actions on their side without impact for all clients.
For example, keeping old API call and convert them on Sailpoint side.
This process could happen for all V3 calls in few years too … What message sent to customer confidence about API Calls.

5

Yes, work is being done to create a public API for governance groups that will replace the v2 workgroups. The priority is to deprecate /cc first, and then v2, so you have quite some time before we announce a deprecation of v2 workgroups.

1 Like
6

Updating user permissions will be a part of the new v3 Identity API that is being worked on.

2 Likes
8

Our engineering teams are working hard to provide public, production APIs for the non-public /cc APIs in an effort to maintain existing functionality while updating them to the v3 standard. This will provide a more coherent, documented API portfolio. Please keep an eye on the announcements for API deprecations and the public APIs that will replace them.

The deprecation of our non-public APIs is following a more aggressive schedule due to technical reasons. Our public APIs will follow a more conservative schedule, and the changes between versions likely won’t be as significant as what you are seeing here. Our non-public APIs were never intended to be used outside of IDN, but we know that many of our users rely on them. SailPoint is doing its best to support users during this transition by bringing as many of our non-public APIs to v3 as we can, which will offer better documentation and support in the long run.

9

We are using a number of the older APIs and I’d like to verify that new APIs are being developed for them. Its good to see in comments above that governance groups and IDN permissions is in scope as we are using those.

Here are some others we are using:
Get & Update Campaign Filter
Get, Update, Create, & Delete Applications
Get access profiles associated to app
Reset source
Kick off unoptimized aggregation

4 Likes
10

Hello,

We use these endpoints below to fix issues with connectors and account correlation.

Some of these endpoints were recommended by your own support to fix identity exceptions. I didn’t find similar features in the new APIs.

How are we going to be supported in this situation?

https://tenant.api.identitynow.com/cc/api/source/loadAccounts (disableOptimization: true)
https://tenant.api.identitynow.com/cc/api/source/reset

3 Likes
11

Hi @colin_mckibben

How beta and v3 API going to be supported a source account aggregation? It is a major problem, especially with missing an ability to manage account correlation via disableOptimization and custom schedule source aggregation.
IDN UI source aggregation feature is very limited and does not support real business scenario, for example when the source aggregation must run in a correct sequence to avoid identity data corruption, one after another, and only if/ when a specific another source aggregation in a sequence has been a) finished b) without warning, termination or errors.

We’re patching many heavy sources automatically via API before the API source aggregation call to switch the sources to and from delta/full/nonOptimised/optimised on a base of the previous source aggregation result like ‘processed/terminated/error/deleted account threshold limit/warning’ result.

https://tenant.api.identitynow.com/cc/api/source/loadAccounts

Another area should be added to beta and v3 API to get all tenant cloud executed rules. Currently is the only avalible via cc rule API end point .

https://tenant.api.dentitynow.com/cc/api/rule/list

5 Likes
12

This is great news - if at all possible, it would be fantastic if this endpoint would allow a GET call that would return an identities governance groups so a loopback source could be built for the purpose of being able to leverage approval flows, provisioning and recertifications for managing governance group memberships

1 Like
13

I have noted that these two endpoints are in use, and engineering will determine how best to support their functionality in a v3 API.

1 Like
14

Thanks Dmitri. All cc endpoints will be reviewed, but I am taking notes of specific endpoints like the ones mentioned in this topic, just to make sure we capture their functionality.

1 Like
15

My favorite API is
{{api-url}}/cc/api/source/loadAccounts/{{sourceNumber}}
with disableOptimization set to true

This keeps things in sync, when people add/modify/remove things in our ADUC directly and IdentityNow isn’t aware.

Does anyone know is there a V3 version of this?

3 Likes
16

I would like to add another vote for a production equivalent endpoint for

/cc/api/source/loadAccounts

We use the endpoint to perform optimization disabled aggregations for sources where we are using a custom identity attribute in account correlation config.

The attribute was updated to be searchable using the /cc/api/identityAttribute/update endpoint and is therefore available in the correlation config UI.

However we noticed that accounts aren’t correlated based on the custom attribute during scheduled aggregations. Using the /cc/api/source/loadAccounts with the disableOptimization option does correctly correlate accounts using the custom attribute.

4 Likes
17

I would like to ensure the CC endpoints I use are included in the V3 API. Here are 2 that are very important to us:

  • /cc/api/identityAttribute/update?name=
    We use this to make extended fields searchable and available for account correlation.

  • /cc/api/source/loadAccounts
    Like others, we use this to clean up aggregated data.

1 Like
18

Adding to @kevinrock101 ‘s response
I couldn’t’ find a replacement to /cc/api/user/details in v3 or beta APIs

19

/user/details will likely be replaced by the v3 identity endpoints that are coming soon. We’ll announce the deprecation when they’re ready.

20

Hi @colin_mckibben ,

First of all thank you for this announcement. We are happy to see that these APIs will be replaced by v3 APIs and will afterwards be deprecated. This will undoubtedly improve the quality of the APIs in different ways like visibility and documentation. I have a couple of questions/remarks based on this announcement.

1: “These APIs were not designed for external use”. I was a bit surprised by this remark. After all, In multiple ways, SailPoint has adviced us to use these APIs in the past. For example, SailPoint Support, SailPoint community and even the more recent SailPoint documentation are mentioning these APIs. Some examples are https://documentation.sailpoint.com/saas/help/sources/managing_sources.html#resetting-a-source
https://documentation.sailpoint.com/saas/help/accounts/loading_data.html?#aggregating-account-information-on-a-direct-connect-source-using-apis
In addition, SailPoint’s postman workspace doesn’t mention that the v2 APIs are non-public:
Could you please ensure that SailPoint’s documentation and community pages will refer to the latest version of the API before deprecation occurs?

2: Is it true that you will only deprecate the NON-public APIs that are (going to be) mentioned on the kanban (API Deprecations - SailPoint Developer Community Forum) and that you will not have some kind of script at the end of this year to deprecate all cc/api APIs automatically? We would like to ensure that all APIs we currently use stay functional, unless it has been mentioned in the deprecation column for a significant amount of time (preferably the 12 months you mentioned). Could you perhaps add a column with NON-public APIs that are not yet in the ‘deprecation’ column because they don’t have a v3 equivalent yet? Then we could be able to check if all API endpoints we use are actually documented, and we would be able to contact you if you have forgotten any such API.

3: Since the v3 APIs are designed to be stable and should therefore not change (often), will you ensure that the new v3 APIs will be aligned when it comes to behavior to the current v3 APIs before actually turning on the v3 API? For example, if we have an object (role, source, governance group, segment etc.) that has an owner attribute, will the owner always be looking like the following:
"owner": { "type": "IDENTITY", "id": "2c9180a46faabce4027fb4e018c14239", "name": "Angelo Mekenkamp" }
Where name is uniquely defined for each object to either always be the displayname or always the uid of the identity? Right now this convention is not always the same. Also there is a change in when it complains when you set the owner, for example because you left the name attribute empty or null or because you also added a different attribute like aliasName, that is sometimes a mandatory field, sometimes an optional one and sometimes a forbidden one.
From a scripting perspective it would be great if there is alignment here. Additionality it would make IdentityNow more intuitional when a new object is introduced that happens to have an owner. Same holds for the beta APIs of course, although it makes sense that they are work in progress.

4: Can you please introduce a deprecation warning within each API that will be deprecated? I think best practice dictates to add it in the response header in such a way that every SailPoint API would have this message under the same variable/field/attribute name. Our scripts could then check if this field is set with a deprecation code/message and provide a warning message to the developers in some way (maybe together with a scheduled end-of-life date), such that we are aware of the deprecation as soon as we execute the API, without having to check the SailPoint deprecation announcements each time. In a similar way it would be nice if there is a response header mentioning when the API was last updated, such that we could check the documentation in case the API behaves differently than before.

3 Likes
21

Hello,

On July 2021 I used the private api {{api_url}}/cc/api/integration/createSimIntegration to create a service desk integration.
Now If use the v3/beta api to list the created sdim the answer is an empty array.
Our sdim is working in production environment.
I hope that when the private api will not available anymore, the v3/beta api will be able to manage our sdim.

Regards,
Giuseppe