Guide-level explanation on how to manage users with the admin API

[sandhose]

In addition to reference documentation on the various bits related to the GraphQL API, it would be helpful to have a step-by-step guide on how to leverage with the API. Issues for the individual bits needed first:

• Document how to leverage the client_credentials grant to gain admin-level API access #2604
• Document the default policy behaviour around admin scopes #2187
• Integrate or link GraphQL API documentation into main documentation #1712

[sandhose]

Now that the documentation covers better how the authorisation process works, we could have two "How to" guides:

• How to get a Synapse admin token
  • Cover the easy way: issue a compatibility token via the CLI
  • Cover the interactive way:
    • Make a user admin (during registration in the CLI, or by editing the can_request_admin flag on the user in the database)
    • Do an OAuth 2.0 Device code grant and request the urn:synapse:admin:* scope
• How to interact with the MAS GraphQL API
  • Cover the fully automated way:
    • Define a static client
    • Make that client "admin" in the policy
    • Use the client_credentials grant to request the urn:mas:graphl:* and urn:mas:admin scopes
  • Cover the interactive way: Do an OAuth 2.0 Device Code Grant or an Authorisation Code Grant
  • Demo a few operations

Covering the device code grant and/or the authorisation code grant is probably a bit complicated, mainly because of the dynamic client registration… Maybe those should have their own how-to guides?
FTR, I have this shell script to do the device code grant: https://gist.github.com/sandhose/d548c5914870c3777ac9d0aa5c0ef9ef

cc @reivilibre

[sandhose]

The documentation of the new admin API is covering this: https://matrix-org.github.io/matrix-authentication-service/topics/admin-api.html

We're still missing a few APIs, which is tracked in #3057