organization roles that are required to assign space roles are inconsistent between API specification and actual behaviour

[kanngiesser]

Issue

The specification for CF API v3 describes requirements for organization roles, that must be met before assigning space roles via POST /v3/roles. The documented requirements are inconsistent with the actual behavior.

Context

The specification for CF API v3 describes requirements for organization roles, that must be met before assigning space roles via POST /v3/roles:

For a user to be assigned a space role, the user must already have an organization role in the parent organization.

In practice, however, the API call which assigns a space role, returns successfully only in case the user has organization_user on the parent organization. This behavior has been documented at #3377.

The API call to assign a space role fails in case the user has any other role on the parent organization, e.g. organization_auditor. This behavior is not expected from the API specification.

Steps to Reproduce

No response

Expected Result

No response

Current Result

No response

Possible Fix

The API documentation for POST /v3/roles should describe the actual behavior until #3377 is implemented:

For a user to be assigned a space role, the user must already have the `organization_user` role in the parent organization.