From d9c447e194180df5efa75ab25803d317d7df5f7f Mon Sep 17 00:00:00 2001
From: Johannes Marbach <n0-0ne+github@mailbox.org>
Date: Fri, 19 Jul 2024 12:13:10 +0200
Subject: [PATCH] Document m.get_login_token capability (#1908)

---
 .../newsfragments/1908.clarification          |  1 +
 content/client-server-api/_index.md           | 21 +++++++++++++++++++
 data/api/client-server/capabilities.yaml      |  4 ++++
 data/api/client-server/login_token.yaml       |  6 +++---
 4 files changed, 29 insertions(+), 3 deletions(-)
 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 00000000..d9dc2e8c
--- /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).
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index ba013735..1a6f1c6e 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 unable 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 fc5b47e2..3ae26b22 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 19fa350e..f14e1a0a 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: