Document m.get_login_token capability

Fixes: #1547 Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>
matrix-org · Jul 12, 2024 · 6972b57 · 6972b57
1 parent 40d5e48
commit 6972b57
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 3 deletions.
diff --git 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
@@ -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
@@ -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: