I have taken a look at these endpoints and provided my questions/remarks and feedback for improvements here. I think it would be nice if the feedback can be taken into account before these /beta APIs are turned into /v3, /v4, /v2024 or /v2025 APIs.
Regarding POST /beta/source-apps, Attributes that can be patched can not always be directly given when creating the account. In general you should be able to pass the full object when creating the object. Currently, in order to create it, one would first need to create the application and then update the application. Examples are enabled, owner, provisionRequestEnabled, appCenterEnabled and accessProfiles. It would be good if we can define the whole object from the start.
Regarding POST /beta/source-apps/bulk-update, is this API an atomic operation? A.K.A., if it fails to patch one access profile, will it ensure that all source apps are not updated as well? If not, is it able to tell us which source apps were succesfully updated and which ones were not?
Regarding GET /beta/source-apps/assigned, the documentation says âThis API returns the list of source apps assigned for logged in user.â. I donât quite follow this sentence, what does this mean? Is this returning a list of source apps assigned to a particular identity (user is written singular)? I think not since neither the URL path nor the query parameters demand an identity ID. What does the âlogged inâ part mean here?
/beta/roles gives me all roles (including the ones not available for access requests), /beta/transforms gives me all transforms, why is /beta/source-apps not returning all source apps, but only the ones available for access requests? To get all source-apps we would now need to call /beta/source-apps/all. It would make more sense to me if /beta/source-apps will return all source-apps and that if we want to filter on specific ones (assigned, requestable), we use the standard approach of using the filter parameter similar to /beta/source-apps?filter=accountSource.id eq "1234..." and /beta/source-apps?filter=enabled eq true.
Why is the scope for GET /beta/source-apps/allidn:app-roles:manage instead of idn:app-roles:read?
Why does the source-app has the attribute called acccountSource instead of just source? We also list the sources through /v3/sources and not through something like /v3/account-sources. I saw that also GET /beta/user-apps point to source
Why is the endpoint called source-apps, whilst the UI uses the term applications. Even within the API the object is refered to with type APPLICATION. These multiple naming conventions seems quite confusing to me.
What is the difference between a source-app and a user-app? The naming suggests that there are two different types of apps, source-apps and user-apps, but it seems as if is user-app the mapping between applications (source-apps) and the identities that have them? Perhaps for mappings like a standard like /beta/application-identity-mappings would be more suitable for mapping endpoints?
Regarding GET /beta/user-apps/:id/available-accounts. This API expects the id of the user app, and returns an array of available accounts. When is an account considered available? The response also contains for each account the appId and appDisplayName. Why is this? We already give the id within the URL path, so shouldnât the response give this same value for each available account? Seems like this is information not worth sending.
What is the difference between GET beta/user-apps/all and GET beta/user-apps? Similar remark as point 4 probably applies here, although here it looks like these endpoints are duplicates of each other, with only minor changes such as the possible filter options.
Regarding PATCH /beta/user-apps/:id, what happens if we change the account, will ISC directly provision the newly chosen account and deprovision the previous chosen account? According the the documentation, the scope for this API is idn:app-roles:read.
Hi Angelo, thank you for reviewing our API documentation and providing feedback. We really appreciate it.
Regarding POST /beta/source-apps, Attributes that can be patched can not always be directly given when creating the account. In general you should be able to pass the full object when creating the object. Currently, in order to create it, one would first need to create the application and then update the application. Examples are enabled, owner, provisionRequestEnabled, appCenterEnabled and accessProfiles. It would be good if we can define the whole object from the start.
We agree that it would be better to support define all attributes when creating. The beta app API currently directly replaces the legacy cc API. In the cc/app/create function, itâs not possible to specify other attribute changes. We will definitely gather feedback and make improvements in the next iteration. Right now, we need to keep the beta app API and cc app API same because there is data sync between the two backend systems.
Regarding POST /beta/source-apps/bulk-update, is this API an atomic operation? A.K.A., if it fails to patch one access profile, will it ensure that all source apps are not updated as well? If not, is it able to tell us which source apps were succesfully updated and which ones were not?
In most cases, the API is not an atomic operation. We have created a ticket to improve this API so that it can provide clear responses to users.
Regarding GET /beta/source-apps/assigned, the documentation says âThis API returns the list of source apps assigned for logged in user.â. I donât quite follow this sentence, what does this mean? Is this returning a list of source apps assigned to a particular identity (user is written singular)? I think not since neither the URL path nor the query parameters demand an identity ID. What does the âlogged inâ part mean here?
/beta/roles gives me all roles (including the ones not available for access requests), /beta/transforms gives me all transforms, why is /beta/source-apps not returning all source apps, but only the ones available for access requests? To get all source-apps we would now need to call /beta/source-apps/all. It would make more sense to me if /beta/source-apps will return all source-apps and that if we want to filter on specific ones (assigned, requestable), we use the standard approach of using the filter parameter similar to /beta/source-apps?filter=accountSource.id eq "1234..." and /beta/source-apps?filter=enabled eq true.
Why is the scope for GET /beta/source-apps/allidn:app-roles:manage instead of idn:app-roles:read?
We will provide an API mapping document later for the legacy CC API and the beta API. We hope that this document can provide more context about our new beta APIs.
Why does the source-app has the attribute called acccountSource instead of just source? We also list the sources through /v3/sources and not through something like /v3/account-sources. I saw that also GET /beta/user-apps point to source
accountSource is from the UI page. Previously, we allowed different source types. Currently, we only support the account source.
Why is the endpoint called source-apps, whilst the UI uses the term applications. Even within the API the object is refered to with type APPLICATION. These multiple naming conventions seems quite confusing to me.
We apologize for any confusion caused. We use âsource appâ because âapplicationâ refers to something different in our backend codes. Therefore, we cannot use âapplication.â
What is the difference between a source-app and a user-app? The naming suggests that there are two different types of apps, source-apps and user-apps, but it seems as if is user-app the mapping between applications (source-apps) and the identities that have them? Perhaps for mappings like a standard like /beta/application-identity-mappings would be more suitable for mapping endpoints?
Yeah, we are going to ask PM about the naming.
Regarding GET /beta/user-apps/:id/available-accounts. This API expects the id of the user app, and returns an array of available accounts. When is an account considered available? The response also contains for each account the appId and appDisplayName. Why is this? We already give the id within the URL path, so shouldnât the response give this same value for each available account? Seems like this is information not worth sending.>
What is the difference between GET beta/user-apps/all and GET beta/user-apps? Similar remark as point 4 probably applies here, although here it looks like these endpoints are duplicates of each other, with only minor changes such as the possible filter options.
please check the mapping document later and see if it can help
Regarding PATCH /beta/user-apps/:id, what happens if we change the account, will ISC directly provision the newly chosen account and deprovision the previous chosen account? According the the documentation, the scope for this API is idn:app-roles:read.
ISC should provision the newly chosen account. The scope is inaccurate, and we have opened a ticket for this issue.
Will it be changed at least before the API gets promoted to a production API? I am afraid if these improvements donât occur from legacy API to beta API and not from beta API to production API, it might take years before this gets changed? ideally changes like this should (according to SailPoint itself), be easy to perform quickly in a solution relying on modular microservices
From a non-IIQ perspective, what are all the different source types in ISC? Using ISC terminology, isnât account source is the only source type, containing basically everything that appears in /v3/sources? After all we donât have something like /v3/account-sources or /v3/sources?filters=type eq "account"
Isnât this strange? Shouldnât end user communication occur using a consistent use of terminology, and shouldnât the mapping of outside world terminology to backend server terminology occur on the server itself rather than on the customer level? I understood that a transform is called a seaspray under the hood and that accounts are called links under the hood. Yet we can also retrieve those objects using /v3/transforms and /v3/accounts. Only other exception I can think of are governance groups, where we have to call /beta/workgroups. I suggest to have this aligned to improve user friendliness. If the backend code wants to use different terminology, that is fine, as long as it can be contained.
Can you please let me know once this document is available? But even with such a document, shouldnât we prefer consistency and let /beta/source-apps return all applications, rather then require an additional endpoint for this, to be similar with the others?
So it will not deprovision the previous selected account? Wouldnât that trigger privilege creep?
@chang_liu, I did look at the document, but it seems to give the same information, sometimes even less, than the API documentation that we currently see. The additional information the document gives is the previous /cc endpoint, but that does not help getting the answers to the questions above. Could you please take a look at them again and see if you could find the answers?
Regarding the following:
I am trying to figure out what this does and why to determine when to use it.
Suppose I have no accounts yet on a source, and we have an application, which is only assigned for specific identities, and the application has one access profile assigned to it. I go to the request center â applications â request the access profile through the application with end date next year, and an account gets created on the source with the entitlements underneath that access profile. Suppose that on the target system a second account is created. We perform account aggregation which detects that account and correlates it to my identity.
I now have the right state to be able to associate a different account to the user app now right? So if I do, the new account has no access, but does have that application? It wonât provision the entitlements of the requested access profile on the new account and the access profile is still provisioned on my original account? What would be the added benefit of associating the application to another application if not for provisioning the access (and deprovision from the original account)? I am currently not understanding why this endpoint in this current behavior would ever be useful.
