matrix/authentication-service
matrix/authentication-service
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-authentication-service.git synced 2025-05-16 17:04:36 +03:00
Code
authentication-service/docs/reference/graphql.md

1.7 KiB
Raw Blame History

GraphQL API

MAS provides a GraphQL API which serves two purposes:

  • it is used by the self-service user interface (usually accessible on /account/), for users to manage their own account
  • it can be used with external tools to manage the service

The endpoint for this API can be discovered through the OpenID Connect discovery document, under the "org.matrix.matrix-authentication-service.graphql_endpoint key. It is though usually hosted at https://<mas-host>/graphql.

GraphQL uses a self-describing schema, which means that the API can be explored in tools like the GraphQL Playground. If enabled, MAS hosts an instance of the playground at https://<mas-host>/graphql/playground.

Authorization

There are two ways to authorize a request to the GraphQL API:

  • if you are requesting from the self-service user interface (or the MAS-hosted GraphQL Playground), it will use the session cookies to authorize as the current user. This mode only allows the user to access their own data, and will never provide admin access.
  • else you will need to provide an OAuth 2.0 access token in the Authorization header, with the Bearer scheme.

The access token must have the urn:mas:graphql:* scope to be able to access the GraphQL API. With only this scope, the session will be authorized as the user who owns the access token, and will only be able to access their own data.

To get full access to the GraphQL API, the access token must have the urn:mas:admin scope in addition to the urn:mas:graphql:* scope.