From 6972b57bac740d8a8dda18d21c53fb29839ba370 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 12 Jul 2024 15:18:09 +0200 Subject: [PATCH 1/3] Document m.get_login_token capability Fixes: #1547 Signed-off-by: Johannes Marbach --- content/client-server-api/_index.md | 21 +++++++++++++++++++++ data/api/client-server/capabilities.yaml | 4 ++++ data/api/client-server/login_token.yaml | 6 +++--- 3 files changed, 28 insertions(+), 3 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index a9c813c4c..5c2495714 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1654,6 +1654,27 @@ An example of the capability API's response for this capability is: } ``` +### `m.get_login_token` capability + +This capability has a single flag, `enabled`, to denote whether the user +is able to use [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) +to generate single-use, time-limited tokens to log unauthenticated clients +into their account. + +When not listed, clients SHOULD assume the user is able to generate tokens. + +An example of the capability API's response for this capability is: + +```json +{ + "capabilities": { + "m.get_login_token": { + "enabled": false + } + } +} +``` + ## Filtering Filters can be created on the server and can be passed as a parameter to diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index fc5b47e27..3ae26b22a 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -80,6 +80,10 @@ paths: $ref: '#/components/schemas/booleanCapability' description: Capability to indicate if the user can change 3PID associations on their account. + m.get_login_token: + $ref: '#/components/schemas/booleanCapability' + description: Capability to indicate if the user can generate tokens to log further + clients into their account. examples: response: value: { diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml index 19fa350ee..f14e1a0af 100644 --- a/data/api/client-server/login_token.yaml +++ b/data/api/client-server/login_token.yaml @@ -33,7 +33,7 @@ paths: Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes this feature if the server is not offering it. Authenticated clients can check for support on - a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation), + a per-user basis with the [`m.get_login_token`](/client-server-api/#mget_login_token-capability) capability, while unauthenticated clients can detect server support by looking for an `m.login.token` login flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login). @@ -98,8 +98,8 @@ paths: The request was malformed, or the user does not have an ability to generate tokens for their devices, as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). - Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token` - [capability](/client-server-api/#capabilities-negotiation). + Clients should verify whether the user has an ability to call this endpoint with the + [`m.get_login_token`](/client-server-api/#mget_login_token-capability) capability. content: application/json: schema: From 72a3c95f70de7f0b1b984655ec5c02ddcba35213 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 12 Jul 2024 15:22:20 +0200 Subject: [PATCH 2/3] Add changelog --- changelogs/client_server/newsfragments/1908.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1908.clarification diff --git a/changelogs/client_server/newsfragments/1908.clarification b/changelogs/client_server/newsfragments/1908.clarification new file mode 100644 index 000000000..d9dc2e8c9 --- /dev/null +++ b/changelogs/client_server/newsfragments/1908.clarification @@ -0,0 +1 @@ +Document the `m.get_login_token` capability as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). From 7e4c4e87b0c37e26dc214ed15572852c26e7375b Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 12 Jul 2024 15:31:09 +0200 Subject: [PATCH 3/3] Default to false if capability is missing --- content/client-server-api/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 5c2495714..cba636e29 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1661,7 +1661,7 @@ is able to use [`POST /login/get_token`](/client-server-api/#post_matrixclientv1 to generate single-use, time-limited tokens to log unauthenticated clients into their account. -When not listed, clients SHOULD assume the user is able to generate tokens. +When not listed, clients SHOULD assume the user is unable to generate tokens. An example of the capability API's response for this capability is: