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: