[ACCESS-2693] Update api spec with permissions information

[wangwillson1]

What does this PR do? What is the motivation?

In the API reference, this PR adds the permissions required to access a given endpoint.

https://docs-staging.datadoghq.com/willson.wang/ACCESS-2693-update-api-spec/api/latest/users/#update-a-user

Merge instructions

• Please wait for a review from aaa-core-access before merging

Additional notes

[srosenthal-dd]

Can you help me understand what this changes means from the user perspective?

Will all API endpoints that start to list permissions in the public docs?

I assume the extra OAuth section is because not all permissions are available in OAuth? I do hope that is a temporary situation in most cases.

We (including PM) should be aware that the actual permission logic is occasionally more complicated. In the example you link, "update a user", the first permission check is an OR, but then it looks specifically at the user/service-account being updated and validates that the caller has the appropriate permission (code)

[wangwillson1]

Will all API endpoints that start to list permissions in the public docs?

all non-rapid endpoints, since API clients is working on adding api spec autogen support for them in the coming weeks

I assume the extra OAuth section is because not all permissions are available in OAuth? I do hope that is a temporary situation in most cases.

yes precisely - ideally we can (one day) just get rid of the whole notion of separate oauth endpoints, but once we get there the docs change will be relatively easy