[doc issue] APIM roles not documented

[bauer-at-work]

Issue description

APIM-related roles go entirely undocumented in the SAP Help. Only APIM role collections are documented.
Still, the documentation boldly claims that it offers a "comprehensive breakdown" as well as "clarity on the responsibilities and access levels within an API Management environment". It seems a bit like a joke.

There should be some hits in the SAP Help when searching for role names like "APIPortalAdmin".

Feedback Type (Optional)

content gaps

Page Title on SAP Help Portal (prefilled)

Comprehensive Breakdown of Role Collections in API Management

Page URL on SAP Help Portal (prefilled)

https://help.sap.com/docs/integration-suite/sap-integration-suite/comprehensive-breakdown-of-role-collections-in-api-management?locale=en-US

[SrutiSagaram]

@bauer-at-work Thank you for your feedback. We will check and get back.

[Kakabira]

@bauer-at-work:
Documenting individual roles could encourage users to create custom role collections by mixing and matching roles. This may lead to unintended access combinations, or conflicting permissions within the API Management environment.
For this reason, the SAP Help documentation focuses on role collections, as they represent the supported and recommended access model.

[bauer-at-work]

Hi @Kakabira, thank you for the information.
I don't believe it. Checking with my contact at SAP on the side.

But if that's really the case, please put your statement also in the documentation so that customers are made aware that they are not supposed to create custom role collections.
Because anyhow, there is still this content gap, just in a different way than expected.

Therefore, please reopen this issue. Thank you!

[Kakabira]

@bauer-at-work : Thank you for your feedback. I understand that the absence of detailed role descriptions in the documentation can create challenges, especially since custom role collections can be created.

We need to further review and groom this topic internally with the Product Management team, and I will make sure to highlight the difficulties you’re encountering so we can address them appropriately. I will keep you informed about the status.

[Kakabira]

@bauer-at-work : The roles in API Management have a one-to-one mapping with the role collections already defined in the document.
Since you are creating a custom role collection with multiple roles, it would be very helpful if you could share more details about the specific scenarios you are trying to address. In particular, could you let us know which role combinations you intend to include in the custom role collection?
I’ve discussed your concern with the Product team, and they would like to better understand the exact combinations being used so they can review and address any potential issues related to supported role configurations.

Your input will help us focus on the relevant scenarios and provide you with more accurate guidance.

Looking forward to your response.

[bauer-at-work]

Hi @Kakabira,

The roles in API Management have a one-to-one mapping with the role collections already defined in the document.

This is crucial info, thanks. Was not aware of that when I opened the issue, but can confirm after checking my subaccount.
However, this issue is not about creating custom role collections – it's about understanding the scope of standard APIM roles.

As I wrote in the issue description:

There should be some hits in the SAP Help when searching for role names like "APIPortalAdmin".

Can you take care of that?

[bauer-at-work]

Looking at the bigger picture, the one-to-one-mapping of role collections to roles effectively leads to the concept of BTP roles being misused as defacto role collections.
My goal is not to combine multiple roles, it is to split authorizations in order to be able to implement segregation of duties (SoD). The poor design of the APIM roles hinders me from doing that.
For example, I need to assign the API Admin role to our developers for them to be able to conduct their work.
This has never been the point of this issue though. But feel free to transmit the feedback to the product team.

My only hope is that the new BTP Integration Cell runtime will be delivered with a proper set of roles and role collections.