Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document m.get_login_token capability #1908

Merged
merged 3 commits into from
Jul 19, 2024
Merged

Document m.get_login_token capability #1908

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6972b57
Document m.get_login_token capability
Johennes Jul 12, 2024
72a3c95
Add changelog
Johennes Jul 12, 2024
7e4c4e8
Default to false if capability is missing
Johennes Jul 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/1908.clarification
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document the `m.get_login_token` capability as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882).
21 changes: 21 additions & 0 deletions content/client-server-api/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MSC3882 doesn't appear to specify how to behave in this case. The only implementations I found are in matrix-js-sdk and matrix-react-sdk and if I'm reading them correctly, they default to enabled == false if the capability is missing.

SHOULD seemed sufficient here because if a client would still call the endpoint, it would simply receive an error response which it must be prepared to handle in any case.


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
Expand Down
4 changes: 4 additions & 0 deletions data/api/client-server/capabilities.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: {
Expand Down
6 changes: 3 additions & 3 deletions data/api/client-server/login_token.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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:
Expand Down