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

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 https://github.com/cloudfoundry/cloud_controller_ng/issues/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 https://github.com/cloudfoundry/cloud_controller_ng/issues/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.

Start with the CF API v3 specification for POST /v3/roles and compare its organization-role requirement with the behavior described here and in issue 3377. Done means the documentation states that a user must already have the organization_user role in the parent organization until the referenced behavior is implemented.