From 885738c840bed7d4e02dc877ba0bb470a4416872 Mon Sep 17 00:00:00 2001 From: Olivier 'reivilibre Date: Wed, 22 Oct 2025 15:45:21 +0100 Subject: [PATCH 1/3] Add basic documentation for personal sessions --- docs/topics/authorization.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/topics/authorization.md b/docs/topics/authorization.md index d2d7ab29c..f81947c12 100644 --- a/docs/topics/authorization.md +++ b/docs/topics/authorization.md @@ -129,6 +129,33 @@ It may also be used in the future as a foundation for a new Application Service This works by presenting the client credentials to get back an access token. The simplest type of client credentials is a client ID and client secret pair, but MAS also supports client authentication with a JWT ([RFC 7523]), which is a robust way to authenticate clients without a shared secret. +## Personal sessions (personal access tokens) + +Personal access tokens are a credential that can be issued to give access to a user, +with predefined scopes and a predefined expiry time. +Either before or after expiry, the token can be regenerated, which produces a new +access token with the same scopes but a new expiry time. + +Personal access tokens are intended to fulfill two basic use cases: + +1. an easy way to obtain a clean token for your own user, for use in automation and scripts; +2. a way to obtain a token for administrative access of another user, either for ad-hoc administrative operations or to set up a bot or similar service. + +In the future, users will be able to create their own personal access tokens, but this is currently not implemented +so (1) is currently not supported. + +For now, personal access tokens must be created by administrators through the [Admin API], satisfying use case (2). +[Element Admin](https://github.com/element-hq/element-admin), available by default in Element Server Suite, can be used to do this interactively. +You can also use the online beta deployment at [admin-beta.element.dev](https://admin-beta.element.dev/). + +### Validity + +Personal sessions can be used so long as: + +- the owner (creator) of the token is still an active and unlocked user (or static OAuth 2 client); and +- the actor (target user, or user being controlled by the token) has not been deactivated. Though the actor is allowed to be locked. + + [MSC4108]: https://github.com/matrix-org/matrix-spec-proposals/pull/4108 [RFC 6749]: https://datatracker.ietf.org/doc/html/rfc6749 [RFC 7523]: https://datatracker.ietf.org/doc/html/rfc7523 @@ -140,3 +167,4 @@ The simplest type of client credentials is a client ID and client secret pair, b [`urn:synapse:admin:*`]: ../reference/scopes.md#urnsynapseadmin [`urn:mas:graphql:*`]: ../reference/scopes.md#urnmasgraphql [`urn:mas:admin`]: ../reference/scopes.md#urnmasadmin +[Admin API]: ./admin-api.md From 1be0b6ced1e35ebfef209a0cd8a93e8393ba6889 Mon Sep 17 00:00:00 2001 From: Olivier 'reivilibre Date: Fri, 24 Oct 2025 12:02:25 +0100 Subject: [PATCH 2/3] Note that you can auth to the admin API with PATs --- docs/topics/admin-api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/topics/admin-api.md b/docs/topics/admin-api.md index 75d5e2b0a..8aa992c76 100644 --- a/docs/topics/admin-api.md +++ b/docs/topics/admin-api.md @@ -46,7 +46,9 @@ If admin API is enabled, MAS will also serve the specification at `/api/spec.jso ## Authentication -All requests to the admin API are gated using access tokens obtained using OAuth 2.0 grants. +All requests to the admin API are gated either using access tokens obtained using OAuth 2.0 grants, +or using personal access tokens (which must currently be issued through the Admin API). + They must have the [`urn:mas:admin`](../reference/scopes.md#urnmasadmin) scope. ### User-interactive tools From 9edf1493cf8ba6faad6afde1d73af5f19621c304 Mon Sep 17 00:00:00 2001 From: Olivier 'reivilibre Date: Tue, 28 Oct 2025 12:22:24 +0000 Subject: [PATCH 3/3] Make clear that owners are the ones to regenerate --- docs/topics/authorization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/topics/authorization.md b/docs/topics/authorization.md index f81947c12..1bdeb8207 100644 --- a/docs/topics/authorization.md +++ b/docs/topics/authorization.md @@ -133,7 +133,7 @@ The simplest type of client credentials is a client ID and client secret pair, b Personal access tokens are a credential that can be issued to give access to a user, with predefined scopes and a predefined expiry time. -Either before or after expiry, the token can be regenerated, which produces a new +Either before or after expiry, the owner of the token can regenerate it, which produces a new access token with the same scopes but a new expiry time. Personal access tokens are intended to fulfill two basic use cases: @@ -144,7 +144,7 @@ Personal access tokens are intended to fulfill two basic use cases: In the future, users will be able to create their own personal access tokens, but this is currently not implemented so (1) is currently not supported. -For now, personal access tokens must be created by administrators through the [Admin API], satisfying use case (2). +For now, personal access tokens must be created, regenerated and revoked by administrators through the [Admin API], satisfying use case (2). [Element Admin](https://github.com/element-hq/element-admin), available by default in Element Server Suite, can be used to do this interactively. You can also use the online beta deployment at [admin-beta.element.dev](https://admin-beta.element.dev/).