mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-30 14:14:09 +02:00
Compare commits
No commits in common. "main" and "v1.18" have entirely different histories.
2
.github/workflows/main.yml
vendored
2
.github/workflows/main.yml
vendored
|
|
@ -1,7 +1,7 @@
|
|||
name: "Spec"
|
||||
|
||||
env:
|
||||
HUGO_VERSION: 0.155.3
|
||||
HUGO_VERSION: 0.153.3
|
||||
PYTHON_VERSION: 3.13
|
||||
NODE_VERSION: 24
|
||||
|
||||
|
|
|
|||
2
.github/workflows/release.yaml
vendored
2
.github/workflows/release.yaml
vendored
|
|
@ -28,7 +28,7 @@ jobs:
|
|||
|
||||
# Ensure npm 11.5.1 or later is installed
|
||||
- name: Update npm
|
||||
run: sudo npm install -g npm@latest
|
||||
run: npm install -g npm@latest
|
||||
|
||||
- name: 🔨 Install dependencies
|
||||
run: "yarn install --frozen-lockfile"
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself.
|
|||
|
||||
1. Install the extended version (often the OS default) of Hugo:
|
||||
<https://gohugo.io/getting-started/installing>. Note that at least Hugo
|
||||
v0.155.0 is required.
|
||||
v0.146.0 is required.
|
||||
|
||||
Alternatively, use the Docker image at
|
||||
https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify SAS commitment calculation for `m.key.verification.accept` messages.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Specify `unsigned.replaces_state` in client-formatted events. Contributed by @nexy7574.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify formats of string types.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix ordering of common error codes.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify formats of string types.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify how to find `via` parameter when following room upgrades.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Specify `m.key_backup` account data, as per [MSC4287](https://github.com/matrix-org/matrix-spec-proposals/pull/4287).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify formats of string types.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update and fix GitHub Actions.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Upgrade Docsy theme to v0.14.3.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Configure a new changelog section for the Olm & Megolm specs.
|
||||
|
|
@ -1 +0,0 @@
|
|||
!.gitignore
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update links to Olm in the Megolm section to point to the Matrix spec.
|
||||
|
|
@ -56,10 +56,6 @@
|
|||
[[tool.towncrier.section]]
|
||||
name = "Room Versions"
|
||||
path = "room_versions"
|
||||
|
||||
[[tool.towncrier.section]]
|
||||
name = "Olm & Megolm"
|
||||
path = "olm_megolm"
|
||||
|
||||
[[tool.towncrier.section]]
|
||||
name = "Appendices"
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify the behaviour and response format of `GET /_matrix/federation/v1/query/profile`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify how multiple signatures should be handled during signature verification. Contributed by @nexy7574.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -70,13 +70,13 @@ copyright = "The Matrix.org Foundation C.I.C."
|
|||
[params.version]
|
||||
# must be one of "unstable", "current", "historical"
|
||||
# this is used to decide whether to show a banner pointing to the current release
|
||||
status = "unstable"
|
||||
status = "stable"
|
||||
# A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner.
|
||||
current_version_url = "https://spec.matrix.org/latest"
|
||||
# The following is used when status = "stable", and is displayed in various UI elements on a released version
|
||||
# of the spec.
|
||||
#major = "1"
|
||||
#minor = "18"
|
||||
major = "1"
|
||||
minor = "18"
|
||||
|
||||
[[params.versions]]
|
||||
# We must include this parameter to enable docsy's version picker in the navbar. The picker
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@ this.
|
|||
|
||||
### Homeserver -> Application Service API
|
||||
|
||||
#### Authorisation
|
||||
#### Authorization
|
||||
|
||||
{{% changed-in v="1.4" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ No significant changes.
|
|||
|
||||
**Spec Clarifications**
|
||||
|
||||
- For room versions 6 and 7, clarify in the authorisation rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
|
||||
- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
|
||||
- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066))
|
||||
- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070))
|
||||
- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114))
|
||||
|
|
|
|||
|
|
@ -108,12 +108,12 @@ No significant changes.
|
|||
|
||||
|
||||
- Improve readability and understanding of the state resolution algorithms. ([#1037](https://github.com/matrix-org/matrix-spec/issues/1037), [#1042](https://github.com/matrix-org/matrix-spec/issues/1042), [#1043](https://github.com/matrix-org/matrix-spec/issues/1043), [#1120](https://github.com/matrix-org/matrix-spec/issues/1120))
|
||||
- Improve readability of the authorisation rules. ([#1050](https://github.com/matrix-org/matrix-spec/issues/1050))
|
||||
- Improve readability of the authorization rules. ([#1050](https://github.com/matrix-org/matrix-spec/issues/1050))
|
||||
- For room versions 8, 9, and 10: clarify which homeserver is required to sign the join event. ([#1093](https://github.com/matrix-org/matrix-spec/issues/1093))
|
||||
- Clarify that room versions 1 through 9 accept stringy power levels, as noted by [MSC3667](https://github.com/matrix-org/matrix-spec-proposals/pull/3667). ([#1099](https://github.com/matrix-org/matrix-spec/issues/1099))
|
||||
- For all room versions: Add `m.federate` to the authorisation rules, as originally intended. ([#1103](https://github.com/matrix-org/matrix-spec/issues/1103))
|
||||
- For all room versions: Add `m.federate` to the authorization rules, as originally intended. ([#1103](https://github.com/matrix-org/matrix-spec/issues/1103))
|
||||
- For room versions 2 through 10: More explicitly define the mainline of a power event and the mainline ordering of other events. ([#1107](https://github.com/matrix-org/matrix-spec/issues/1107))
|
||||
- For room versions 7, 8, 9, and 10: fix join membership authorisation rules when `join_rule` is `knock`. ([#3737](https://github.com/matrix-org/matrix-spec-proposals/issues/3737))
|
||||
- For room versions 7, 8, 9, and 10: fix join membership authorization rules when `join_rule` is `knock`. ([#3737](https://github.com/matrix-org/matrix-spec-proposals/issues/3737))
|
||||
|
||||
|
||||
## Appendices
|
||||
|
|
|
|||
|
|
@ -73,7 +73,7 @@ date: 2022-09-29
|
|||
<strong>Breaking Changes</strong>
|
||||
|
||||
|
||||
- Replace homeserver authorisation approach with an `Authorization` header instead of `access_token` when talking to the application service, as per [MSC2832](https://github.com/matrix-org/matrix-spec-proposals/pull/2832). ([#1200](https://github.com/matrix-org/matrix-spec/issues/1200))
|
||||
- Replace homeserver authorization approach with an `Authorization` header instead of `access_token` when talking to the application service, as per [MSC2832](https://github.com/matrix-org/matrix-spec-proposals/pull/2832). ([#1200](https://github.com/matrix-org/matrix-spec/issues/1200))
|
||||
|
||||
|
||||
<strong>Spec Clarifications</strong>
|
||||
|
|
|
|||
|
|
@ -126,25 +126,6 @@ state (e.g.: sending messages, account data, etc) and not routes which
|
|||
only read state (e.g.: [`/sync`](#get_matrixclientv3sync),
|
||||
[`/user/{userId}/account_data/{type}`](#get_matrixclientv3useruseridaccount_datatype), etc).
|
||||
|
||||
`M_UNKNOWN`
|
||||
: An unknown error has occurred.
|
||||
|
||||
`M_UNKNOWN_DEVICE`
|
||||
: {{% added-in v="1.17" %}} The device ID supplied by the application service does
|
||||
not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
|
||||
|
||||
`M_UNKNOWN_TOKEN`
|
||||
: The access or refresh token specified was not recognised.
|
||||
|
||||
: An additional response parameter, `soft_logout`, might be present on the
|
||||
response for 401 HTTP status codes. See [the soft logout
|
||||
section](#soft-logout) for more information.
|
||||
|
||||
`M_UNRECOGNIZED`
|
||||
: The server did not understand the request. This is expected to be returned with
|
||||
a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
|
||||
code if the endpoint is implemented, but the incorrect HTTP method is used.
|
||||
|
||||
`M_USER_LIMIT_EXCEEDED`
|
||||
: {{% added-in v="1.18" %}} The request cannot be completed because the user has
|
||||
exceeded (or the request would cause them to exceed) a limit associated with
|
||||
|
|
@ -176,6 +157,25 @@ limit is a hard limit that cannot be increased.
|
|||
}
|
||||
```
|
||||
|
||||
`M_UNKNOWN`
|
||||
: An unknown error has occurred.
|
||||
|
||||
`M_UNKNOWN_DEVICE`
|
||||
: {{% added-in v="1.17" %}} The device ID supplied by the application service does
|
||||
not belong to the user ID during [identity assertion](/application-service-api/#identity-assertion).
|
||||
|
||||
`M_UNKNOWN_TOKEN`
|
||||
: The access or refresh token specified was not recognised.
|
||||
|
||||
: An additional response parameter, `soft_logout`, might be present on the
|
||||
response for 401 HTTP status codes. See [the soft logout
|
||||
section](#soft-logout) for more information.
|
||||
|
||||
`M_UNRECOGNIZED`
|
||||
: The server did not understand the request. This is expected to be returned with
|
||||
a 404 HTTP status code if the endpoint is not implemented or a 405 HTTP status
|
||||
code if the endpoint is implemented, but the incorrect HTTP method is used.
|
||||
|
||||
`M_USER_LOCKED`
|
||||
: The account has been [locked](#account-locking) and cannot be used at this time.
|
||||
|
||||
|
|
@ -263,7 +263,7 @@ matching the threepid was found.
|
|||
: The request or entity was too large.
|
||||
|
||||
`M_UNAUTHORIZED`
|
||||
: The request was not correctly authorised. Usually due to login failures.
|
||||
: The request was not correctly authorized. Usually due to login failures.
|
||||
|
||||
`M_UNSUPPORTED_ROOM_VERSION`
|
||||
: The client's request to create a room used a room version that the
|
||||
|
|
@ -543,7 +543,7 @@ With the legacy API, a client can register a new account with the
|
|||
With the OAuth 2.0 API, a client can't register a new account directly. The end
|
||||
user must do that directly in the homeserver's web UI. However, the client can
|
||||
signal to the homeserver that the user wishes to create a new account with the
|
||||
[`prompt=create`](#user-registration) parameter during authorisation.
|
||||
[`prompt=create`](#user-registration) parameter during authorization.
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.17" %}}
|
||||
|
|
@ -559,7 +559,7 @@ endpoint. To invalidate the access token the client must call the [`/logout`](#p
|
|||
endpoint.
|
||||
|
||||
With the OAuth 2.0 API, a client can obtain an access token by using one of the
|
||||
[grant types](#grant-types) supported by the homeserver and authorising the
|
||||
[grant types](#grant-types) supported by the homeserver and authorizing the
|
||||
proper [scope](#scope), as demonstrated in the [login flows](#login-flows). To
|
||||
invalidate the access token the client must use [token revocation](#token-revocation).
|
||||
|
||||
|
|
@ -1736,7 +1736,7 @@ or best practice recommendations.
|
|||
|
||||
The main change for end users with this API is that all the account management
|
||||
occurs in their browser on the homeserver's web UI. This is where they will
|
||||
register a new account or log into an existing account and authorise a client to
|
||||
register a new account or log into an existing account and authorize a client to
|
||||
access their Matrix account. This means that the homeserver has complete control
|
||||
over the requirements to create a new account and is not limited by the steps
|
||||
defined in this specification. It also means that less trust is given to clients
|
||||
|
|
@ -1757,27 +1757,27 @@ authentication type.
|
|||
|
||||
1. [Discover the OAuth 2.0 server metadata](#server-metadata-discovery).
|
||||
2. [Register the client with the homeserver](#client-registration).
|
||||
3. [Obtain an access token](#login-flows) by authorising a [scope](#scope) for
|
||||
the client with the [authorisation code grant](#authorisation-code-grant) or
|
||||
[device authorisation grant](#device-authorisation-grant).
|
||||
3. [Obtain an access token](#login-flows) by authorizing a [scope](#scope) for
|
||||
the client with the [authorization code grant](#authorization-code-grant) or
|
||||
[device authorization grant](#device-authorization-grant).
|
||||
4. [Refresh the access token](#token-refresh-flow) with the [refresh token grant](#refresh-token-grant) when it expires.
|
||||
5. [Revoke the tokens](#token-revocation) when the users wants to log out of the client.
|
||||
|
||||
#### Login flows
|
||||
|
||||
Logging in and obtaining an access token with the OAuth 2.0 API should be done
|
||||
using either the [authorisation code grant](#authorisation-code-grant) or
|
||||
[device authorisation grant](#device-authorisation-grant). In the context of the
|
||||
using either the [authorization code grant](#authorization-code-grant) or
|
||||
[device authorization grant](#device-authorization-grant). In the context of the
|
||||
Matrix specification, this means requesting a [scope](#scope) including full
|
||||
client-server API read/write access and allocating a device ID.
|
||||
|
||||
##### Authorisation code flow
|
||||
##### Authorization code flow
|
||||
|
||||
This login flow uses the [authorisation code grant](#authorisation-code-grant)
|
||||
This login flow uses the [authorization code grant](#authorization-code-grant)
|
||||
and is suitable for clients where the following criteria are met:
|
||||
|
||||
- There is a web browser available for the user to complete authentication and
|
||||
authorisation.
|
||||
authorization.
|
||||
- The client can receive the callback via a redirect from the web browser.
|
||||
|
||||
Once the client has retrieved the [server metadata](#server-metadata-discovery)
|
||||
|
|
@ -1786,20 +1786,20 @@ the client needs to generate the following values:
|
|||
- `device_id`: a unique identifier for this device; see the
|
||||
[`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
|
||||
- `state`: a unique opaque identifier, like a [transaction ID](#transaction-identifiers),
|
||||
that will allow the client to maintain state between the authorisation request
|
||||
that will allow the client to maintain state between the authorization request
|
||||
and the callback.
|
||||
- `code_verifier`: a cryptographically random value that will allow to make sure
|
||||
that the client that makes the token request for a given `code` is the same
|
||||
one that made the authorisation request.
|
||||
one that made the authorization request.
|
||||
|
||||
It is defined in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) as
|
||||
a high-entropy cryptographic random string using the characters `[A-Z]`,
|
||||
`[a-z]`, `[0-9]`, `-`, `.`, `_` and `~` with a minimum length of 43 characters
|
||||
and a maximum length of 128 characters.
|
||||
|
||||
**Authorisation request**
|
||||
**Authorization request**
|
||||
|
||||
The client then constructs the authorisation request URL using the
|
||||
The client then constructs the authorization request URL using the
|
||||
`authorization_endpoint` value, with the following query parameters:
|
||||
|
||||
| Parameter | Value |
|
||||
|
|
@ -1813,7 +1813,7 @@ The client then constructs the authorisation request URL using the
|
|||
| `code_challenge` | Computed from the `code_verifier` value generated previously using the SHA-256 algorithm, as described in [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636). |
|
||||
| `code_challenge_method` | `S256` |
|
||||
|
||||
This authorisation request URL must be opened in the user's browser:
|
||||
This authorization request URL must be opened in the user's browser:
|
||||
|
||||
- For web-based clients, this can be done through a redirection or by opening
|
||||
the URL in a new tab.
|
||||
|
|
@ -1822,7 +1822,7 @@ This authorisation request URL must be opened in the user's browser:
|
|||
[`ASWebAuthenticationSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession)
|
||||
on iOS or [Android Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs).
|
||||
|
||||
Sample authorisation request, with extra whitespaces for readability:
|
||||
Sample authorization request, with extra whitespaces for readability:
|
||||
|
||||
```nohighlight
|
||||
https://account.example.com/oauth2/auth?
|
||||
|
|
@ -1839,7 +1839,7 @@ https://account.example.com/oauth2/auth?
|
|||
<a id="callback"></a> **Callback**
|
||||
|
||||
Once completed, the user is redirected to the `redirect_uri`, with either a
|
||||
successful or failed authorisation in the URL fragment or query parameters.
|
||||
successful or failed authorization in the URL fragment or query parameters.
|
||||
Whether the parameters are in the URL fragment or query parameters is determined
|
||||
by the `response_mode` value:
|
||||
|
||||
|
|
@ -1853,15 +1853,15 @@ clients SHOULD use the `fragment` response mode if the `redirect_uri` is an
|
|||
HTTPS URI with a remote host.
|
||||
|
||||
In both success and failure cases, the parameters will include the `state` value
|
||||
used in the authorisation request.
|
||||
used in the authorization request.
|
||||
|
||||
A successful authorisation will have a `code` value, for example:
|
||||
A successful authorization will have a `code` value, for example:
|
||||
|
||||
```nohighlight
|
||||
https://app.example.com/oauth2-callback#state=ewubooN9weezeewah9fol4oothohroh3&code=iuB7Eiz9heengah1joh2ioy9ahChuP6R
|
||||
```
|
||||
|
||||
A failed authorisation will have the following values:
|
||||
A failed authorization will have the following values:
|
||||
|
||||
- `error`: the error code
|
||||
- `error_description`: the error description (optional)
|
||||
|
|
@ -1875,7 +1875,7 @@ https://app.example.com/oauth2-callback#state=ewubooN9weezeewah9fol4oothohroh3&e
|
|||
|
||||
**Token request**
|
||||
|
||||
The client then exchanges the authorisation code to obtain an access token using
|
||||
The client then exchanges the authorization code to obtain an access token using
|
||||
the token endpoint.
|
||||
|
||||
This is done by making a POST request to the `token_endpoint` with the following
|
||||
|
|
@ -1885,9 +1885,9 @@ parameters, encoded as `application/x-www-form-urlencoded` in the body:
|
|||
|-----------------|------------------------------------------------------------|
|
||||
| `grant_type` | `authorization_code` |
|
||||
| `code` | The value of `code` obtained from the callback. |
|
||||
| `redirect_uri` | The same `redirect_uri` used in the authorisation request. |
|
||||
| `redirect_uri` | The same `redirect_uri` used in the authorization request. |
|
||||
| `client_id` | The client ID returned from client registration. |
|
||||
| `code_verifier` | The value generated at the start of the authorisation flow. |
|
||||
| `code_verifier` | The value generated at the start of the authorization flow. |
|
||||
|
||||
The server replies with a JSON object containing the access token, the token
|
||||
type, the expiration time, and the refresh token.
|
||||
|
|
@ -1922,13 +1922,13 @@ Sample response:
|
|||
Finally, the client can call the [`/whoami`](#get_matrixclientv3accountwhoami)
|
||||
endpoint to get the user ID that owns the access token.
|
||||
|
||||
##### Device authorisation flow
|
||||
##### Device authorization flow
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
This flow uses the [device authorisation grant](#device-authorisation-grant) to
|
||||
This flow uses the [device authorization grant](#device-authorization-grant) to
|
||||
allow clients to obtain an access token without needing to directly interact
|
||||
with a web browser. Instead, the user completes authorisation on a web browser
|
||||
with a web browser. Instead, the user completes authorization on a web browser
|
||||
that can be a separate device.
|
||||
|
||||
This is useful for devices with limited input
|
||||
|
|
@ -1941,7 +1941,7 @@ the client needs to generate following value:
|
|||
- `device_id`: a unique identifier for this device; see the
|
||||
[`urn:matrix:client:device:<device_id>`](#device-id-allocation) scope token.
|
||||
|
||||
**Device authorisation request**
|
||||
**Device authorization request**
|
||||
|
||||
The client sends a `application/x-www-form-urlencoded` encoded `POST` request to
|
||||
the `device_authorization_endpoint` as defined in
|
||||
|
|
@ -1952,7 +1952,7 @@ the `device_authorization_endpoint` as defined in
|
|||
| `client_id` | The client ID returned from client registration. |
|
||||
| `scope` | `urn:matrix:client:api:* urn:matrix:client:device:<device_id>` with the `device_id` generated previously. |
|
||||
|
||||
Sample device authorisation request:
|
||||
Sample device authorization request:
|
||||
|
||||
```
|
||||
POST /oauth2/device HTTP/1.1
|
||||
|
|
@ -1962,7 +1962,7 @@ Content-Type: application/x-www-form-urlencoded
|
|||
client_id=s6BhdRkqt3&scope=urn%3Amatrix%3Aclient%3Aapi%3A%2A%20urn%3Amatrix%3Aclient%3Adevice%3AAABBBCCCDDD
|
||||
```
|
||||
|
||||
**Device authorisation response**
|
||||
**Device authorization response**
|
||||
|
||||
The server responds with a JSON object as defined in
|
||||
[RFC 8628 section 3.2](https://datatracker.ietf.org/doc/html/rfc8628#section-3.2),
|
||||
|
|
@ -1972,7 +1972,7 @@ containing:
|
|||
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `device_code` | The device verification code. |
|
||||
| `user_code` | An end-user verification code. |
|
||||
| `verification_uri` | The end-user verification URI on the authorisation server. |
|
||||
| `verification_uri` | The end-user verification URI on the authorization server. |
|
||||
| `verification_uri_complete` | Optionally, the URI which doesn't require the user to manually type the `user_code`, designed for non-textual transmission. |
|
||||
| `expires_in` | The lifetime in seconds of the `device_code` and `user_code`. |
|
||||
| `interval` | The minimum number of seconds the client should wait between polling requests to the token endpoint. If omitted, clients should default to 5. |
|
||||
|
|
@ -2009,13 +2009,13 @@ specific device characteristics and use case. For example:
|
|||
`verification_uri`) in the system browser.
|
||||
|
||||
The user opens the verification URI in a web browser, which may be on another
|
||||
device, and completes authentication and authorisation.
|
||||
device, and completes authentication and authorization.
|
||||
|
||||
**Token polling**
|
||||
|
||||
While the user is completing authorisation, the client polls the
|
||||
While the user is completing authorization, the client polls the
|
||||
`token_endpoint` for the outcome, at intervals no shorter than the `interval`
|
||||
value from the device authorisation response.
|
||||
value from the device authorization response.
|
||||
|
||||
The poll request is a `POST` to the `token_endpoint` with the following
|
||||
parameters, encoded as `application/x-www-form-urlencoded` in the body:
|
||||
|
|
@ -2023,7 +2023,7 @@ parameters, encoded as `application/x-www-form-urlencoded` in the body:
|
|||
| Parameter | Value |
|
||||
|---------------|----------------------------------------------------------------|
|
||||
| `grant_type` | `urn:ietf:params:oauth:grant-type:device_code` |
|
||||
| `device_code` | The `device_code` from the device authorisation response. |
|
||||
| `device_code` | The `device_code` from the device authorization response. |
|
||||
| `client_id` | The client ID returned from client registration. |
|
||||
|
||||
Sample token polling request:
|
||||
|
|
@ -2039,11 +2039,11 @@ grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=Gm
|
|||
The server responds as defined in [RFC 8628 section
|
||||
3.5](https://datatracker.ietf.org/doc/html/rfc8628#section-3.5):
|
||||
|
||||
- While authorisation is pending, the server returns an `authorization_pending`
|
||||
- While authorization is pending, the server returns an `authorization_pending`
|
||||
error (or `slow_down` if the client is polling too frequently).
|
||||
- If authorisation is denied, the server returns an `access_denied` error.
|
||||
- If authorization is denied, the server returns an `access_denied` error.
|
||||
- If the device code expires, the server returns an `expired_token` error.
|
||||
- On successful authorisation, the server returns a JSON object containing the
|
||||
- On successful authorization, the server returns a JSON object containing the
|
||||
access token, token type, expiration time, refresh token, and scope:
|
||||
|
||||
```json
|
||||
|
|
@ -2075,7 +2075,7 @@ request to the `token_endpoint` with the following parameters, encoded as
|
|||
| `client_id` | The client ID returned from client registration. |
|
||||
|
||||
The server replies with a JSON object containing the new access token, the token
|
||||
type, the expiration time, and a new refresh token, like in the authorisation
|
||||
type, the expiration time, and a new refresh token, like in the authorization
|
||||
flow.
|
||||
|
||||
#### Server metadata discovery
|
||||
|
|
@ -2084,7 +2084,7 @@ flow.
|
|||
|
||||
#### Client registration
|
||||
|
||||
Before being able to use the authorisation flow to obtain an access token, a
|
||||
Before being able to use the authorization flow to obtain an access token, a
|
||||
client needs to obtain a `client_id` by registering itself with the server.
|
||||
|
||||
This should be done via OAuth 2.0 Dynamic Client Registration as defined in
|
||||
|
|
@ -2092,7 +2092,7 @@ This should be done via OAuth 2.0 Dynamic Client Registration as defined in
|
|||
|
||||
##### Client metadata
|
||||
|
||||
In OAuth 2.0, clients register a set of metadata values with the authorisation
|
||||
In OAuth 2.0, clients register a set of metadata values with the authorization
|
||||
server, which associates it with a newly generated `client_id`. These values are
|
||||
used to describe the client to the user and define how the client interacts with
|
||||
the server.
|
||||
|
|
@ -2172,7 +2172,7 @@ With the same client URI, the following are invalid redirect URIs:
|
|||
- The scheme MUST be `http`.
|
||||
- The host part MUST be `localhost`, `127.0.0.1`, or `[::1]`.
|
||||
- There MUST NOT be a port. The homeserver MUST then accept any port number
|
||||
during the authorisation flow.
|
||||
during the authorization flow.
|
||||
3. **Claimed `https` Scheme URI**
|
||||
|
||||
Some operating systems allow apps to claim `https` scheme URIs in the
|
||||
|
|
@ -2271,7 +2271,7 @@ choose to delete client registrations that don't have an active session. The
|
|||
server MUST NOT delete client registrations that have an active session.
|
||||
|
||||
Clients MUST perform a new client registration at the start of each
|
||||
authorisation flow.
|
||||
authorization flow.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Because each client on each user device will do its own registration, they may
|
||||
|
|
@ -2287,7 +2287,7 @@ registrations.
|
|||
|
||||
#### Scope
|
||||
|
||||
The client requests a scope in the OAuth 2.0 authorisation flow, which is then
|
||||
The client requests a scope in the OAuth 2.0 authorization flow, which is then
|
||||
associated to the generated access and refresh tokens. This provides a framework
|
||||
for obtaining user consent.
|
||||
|
||||
|
|
@ -2380,7 +2380,7 @@ This definition matches:
|
|||
[RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) and other RFCs define
|
||||
several "grant types": ways to obtain an ["access token"](#using-access-tokens).
|
||||
|
||||
All these grants types require the client to know the following [authorisation
|
||||
All these grants types require the client to know the following [authorization
|
||||
server metadata](#server-metadata-discovery):
|
||||
- `token_endpoint`
|
||||
- `grant_types_supported`
|
||||
|
|
@ -2388,17 +2388,17 @@ server metadata](#server-metadata-discovery):
|
|||
The client must also have obtained a `client_id` by [registering with the server](#client-registration).
|
||||
|
||||
This specification supports the following grant types:
|
||||
- [Authorisation code grant](#authorisation-code-grant)
|
||||
- {{% added-in v="1.18" %}} [Device authorisation grant](#device-authorisation-grant)
|
||||
- [Authorization code grant](#authorization-code-grant)
|
||||
- {{% added-in v="1.18" %}} [Device authorization grant](#device-authorization-grant)
|
||||
- [Refresh token grant](#refresh-token-grant)
|
||||
|
||||
##### Authorisation code grant
|
||||
##### Authorization code grant
|
||||
|
||||
As per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1),
|
||||
the authorisation code grant lets the client obtain an access token through a
|
||||
the authorization code grant lets the client obtain an access token through a
|
||||
browser redirect.
|
||||
|
||||
This grant requires the client to know the following [authorisation server
|
||||
This grant requires the client to know the following [authorization server
|
||||
metadata](#server-metadata-discovery):
|
||||
- `authorization_endpoint`
|
||||
- `response_types_supported`
|
||||
|
|
@ -2406,7 +2406,7 @@ metadata](#server-metadata-discovery):
|
|||
|
||||
To use this grant, homeservers and clients MUST:
|
||||
|
||||
- Support the authorisation code grant as per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1).
|
||||
- Support the authorization code grant as per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1).
|
||||
- Support the [refresh token grant](#refresh-token-grant).
|
||||
- Support PKCE using the `S256` code challenge method as per [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636).
|
||||
- Use [pre-registered](#client-registration), strict redirect URIs.
|
||||
|
|
@ -2414,34 +2414,34 @@ To use this grant, homeservers and clients MUST:
|
|||
Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
|
||||
for clients with an HTTPS redirect URI.
|
||||
|
||||
##### Device authorisation grant
|
||||
##### Device authorization grant
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
As per [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), the device
|
||||
authorisation grant lets clients on devices with limited input capabilities
|
||||
obtain an access token by having the user complete authorisation on a separate
|
||||
authorization grant lets clients on devices with limited input capabilities
|
||||
obtain an access token by having the user complete authorization on a separate
|
||||
device with a web browser.
|
||||
|
||||
This grant requires the client to know the following [authorisation server
|
||||
This grant requires the client to know the following [authorization server
|
||||
metadata](#server-metadata-discovery):
|
||||
|
||||
- `device_authorization_endpoint`
|
||||
|
||||
To use this grant, homeservers and clients MUST:
|
||||
|
||||
- Support the device authorisation grant as per
|
||||
- Support the device authorization grant as per
|
||||
[RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628).
|
||||
- Support the [refresh token grant](#refresh-token-grant).
|
||||
|
||||
As with the [authorisation code grant](#authorisation-code-grant), when
|
||||
authorisation is granted to a client, the homeserver MUST issue a refresh token
|
||||
As with the [authorization code grant](#authorization-code-grant), when
|
||||
authorization is granted to a client, the homeserver MUST issue a refresh token
|
||||
to the client in addition to the access token. The access token and refresh
|
||||
token have the same lifetime constraints as described in the [refresh token
|
||||
grant](#refresh-token-grant) section.
|
||||
|
||||
The full flow for using this grant is described in the
|
||||
[device authorisation flow](#device-authorisation-flow).
|
||||
[device authorization flow](#device-authorization-flow).
|
||||
|
||||
##### Refresh token grant
|
||||
|
||||
|
|
@ -2449,7 +2449,7 @@ As per [RFC 6749 section 6](https://datatracker.ietf.org/doc/html/rfc6749#sectio
|
|||
the refresh token grant lets the client exchange a refresh token for an access
|
||||
token.
|
||||
|
||||
When authorisation is granted to a client, the homeserver MUST issue a refresh
|
||||
When authorization is granted to a client, the homeserver MUST issue a refresh
|
||||
token to the client in addition to the access token.
|
||||
|
||||
The access token MUST be short-lived and SHOULD be refreshed using the
|
||||
|
|
@ -2476,7 +2476,7 @@ When a user wants to log out from a client, the client SHOULD use OAuth 2.0
|
|||
token revocation as defined in [RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009).
|
||||
|
||||
The client makes a `POST` request to the `revocation_endpoint` that can be found
|
||||
in the [authorisation server metadata](#server-metadata-discovery).
|
||||
in the [authorization server metadata](#server-metadata-discovery).
|
||||
|
||||
The body of the request includes the following parameters, encoded as
|
||||
`application/x-www-form-urlencoded`:
|
||||
|
|
@ -2543,7 +2543,7 @@ The server SHOULD return one of the following responses:
|
|||
|
||||
- If the token is already revoked or invalid, the server returns a `200 OK`
|
||||
response
|
||||
- If the client is not authorised to revoke the token, the server returns a
|
||||
- If the client is not authorized to revoke the token, the server returns a
|
||||
`401 Unauthorized` response
|
||||
- For other errors, the server returns a `400 Bad Request` response with error
|
||||
details
|
||||
|
|
@ -2551,18 +2551,18 @@ The server SHOULD return one of the following responses:
|
|||
#### User registration
|
||||
|
||||
Clients can signal to the server that the user desires to register a new account
|
||||
by initiating the [authorisation code grant](#authorisation-code-grant) with the `prompt=create` parameter
|
||||
set in the authorisation request as defined in [Initiating User Registration via
|
||||
by initiating the [authorization code grant](#authorization-code-grant) with the `prompt=create` parameter
|
||||
set in the authorization request as defined in [Initiating User Registration via
|
||||
OpenID Connect 1.0](https://openid.net/specs/openid-connect-prompt-create-1_0.html).
|
||||
|
||||
Whether the homeserver supports this parameter is advertised by the
|
||||
`prompt_values_supported` authorisation server metadata.
|
||||
`prompt_values_supported` authorization server metadata.
|
||||
|
||||
Servers that support this parameter SHOULD show the account registration UI in
|
||||
the browser.
|
||||
|
||||
The `prompt=create` parameter is not supported when using the [device
|
||||
authorisation grant](#device-authorisation-grant).
|
||||
authorization grant](#device-authorization-grant).
|
||||
|
||||
#### Account management {id="oauth-20-account-management"}
|
||||
|
||||
|
|
@ -2570,7 +2570,7 @@ authorisation grant](#device-authorisation-grant).
|
|||
|
||||
All account management is done via the homeserver's web UI.
|
||||
|
||||
This specification defines extensions to the [OAuth Authorisation Server
|
||||
This specification defines extensions to the [OAuth Authorization Server
|
||||
Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata)
|
||||
to offer clients a way to deep-link to the account management capabilities of
|
||||
the homeserver to allow the user to complete the account management operations
|
||||
|
|
@ -2578,7 +2578,7 @@ in a browser.
|
|||
|
||||
##### Account management URL discovery
|
||||
|
||||
The [OAuth 2.0 authorisation server metadata](#server-metadata-discovery) is
|
||||
The [OAuth 2.0 authorization server metadata](#server-metadata-discovery) is
|
||||
extended to include the following **optional** fields.
|
||||
|
||||
{{% definition path="schemas/oauth2-account-management-server-metadata" %}}
|
||||
|
|
@ -3120,20 +3120,19 @@ events they have already been sent, and choose to skip sending membership
|
|||
events for members whose membership has not changed. These are called
|
||||
'redundant membership events'. Clients may request that redundant membership
|
||||
events are always included in responses by setting `include_redundant_members`
|
||||
to `true` in the filter.
|
||||
to true in the filter.
|
||||
|
||||
The expected pattern for using lazy-loading is currently:
|
||||
|
||||
- Client performs an initial `/sync` with lazy-loading enabled, and
|
||||
- Client performs an initial /sync with lazy-loading enabled, and
|
||||
receives only the membership events which relate to the senders of
|
||||
the events it receives.
|
||||
- Clients which support display-name tab-completion or other
|
||||
operations which require rapid access to all members in a room
|
||||
should call [`/members`](#get_matrixclientv3roomsroomidmembers) for
|
||||
the currently selected room, with an `?at` parameter set to the
|
||||
`/sync` response's `from` token. The member list for the room is
|
||||
then maintained by the state in subsequent incremental `/sync`
|
||||
responses.
|
||||
should call /members for the currently selected room, with an `?at`
|
||||
parameter set to the /sync response's from token. The member list
|
||||
for the room is then maintained by the state in subsequent
|
||||
incremental /sync responses.
|
||||
- Clients which do not support tab-completion may instead pull in
|
||||
profiles for arbitrary users (e.g. read receipts, typing
|
||||
notifications) on demand by querying the room state or [`/profile`](#get_matrixclientv3profileuserid).
|
||||
|
|
@ -3348,8 +3347,8 @@ room at the start of the returned timeline. The response also includes a
|
|||
`next_batch` field, which should be used as the value of the `since`
|
||||
parameter in the next call to `/sync`. Finally, the response includes,
|
||||
for each room, a `prev_batch` field, which can be passed as a `from`/`to`
|
||||
parameter to the [`/rooms/{roomId}/messages`](#get_matrixclientv3roomsroomidmessages)
|
||||
API to retrieve earlier messages.
|
||||
parameter to the [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API to retrieve earlier
|
||||
messages.
|
||||
|
||||
For example, a `/sync` request might return a range of four events
|
||||
`E2`, `E3`, `E4` and `E5` within a given room, omitting two prior events
|
||||
|
|
@ -3368,8 +3367,7 @@ response to the previous call as the `since` parameter. The client
|
|||
should also pass a `timeout` parameter. The server will then hold open
|
||||
the HTTP connection for a short period of time waiting for new events,
|
||||
returning early if an event occurs. Only the `/sync` API (and the
|
||||
deprecated [`/events`](#get_matrixclientv3events) API) support
|
||||
long-polling in this way.
|
||||
deprecated `/events` API) support long-polling in this way.
|
||||
|
||||
Continuing the example above, an incremental sync might report
|
||||
a single new event `E6`. The response can be visualised as:
|
||||
|
|
@ -3389,7 +3387,7 @@ containing only the most recent message events. A state "delta" is also
|
|||
returned, summarising any state changes in the omitted part of the
|
||||
timeline. The client may therefore end up with "gaps" in its knowledge
|
||||
of the message timeline. The client can fill these gaps using the
|
||||
[`/rooms/{roomId}/messages`](#get_matrixclientv3roomsroomidmessages) API.
|
||||
[`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API.
|
||||
|
||||
Continuing our example, suppose we make a third `/sync` request asking for
|
||||
events since the last sync, by passing the `next_batch` token `x-y-z` as
|
||||
|
|
@ -3412,7 +3410,7 @@ The limited response includes a state delta which describes how the state
|
|||
of the room changes over the gap. This delta explains how to build the state
|
||||
prior to returned timeline (i.e. at `E7`) from the state the client knows
|
||||
(i.e. at `E6`). To close the gap, the client should make a request to
|
||||
[`/rooms/{roomId}/messages`](#get_matrixclientv3roomsroomidmessages)
|
||||
[`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
|
||||
with the query parameters `from=x-y-z` and `to=d-e-f`.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
|
|
@ -4214,13 +4212,13 @@ an automatic propagation event to occur, informing likely-interested
|
|||
parties of the new values. This change is conveyed using two separate
|
||||
mechanisms:
|
||||
|
||||
- an [`m.room.member`](#mroommember) event (with a `join` membership) is sent
|
||||
to every room the user is a member of, to update the `displayname` and
|
||||
- an `m.room.member` event (with a `join` membership) is sent to every
|
||||
room the user is a member of, to update the `displayname` and
|
||||
`avatar_url`.
|
||||
- an [`m.presence`](#mpresence) presence status update is sent, again
|
||||
containing the new values of the `displayname` and `avatar_url` keys, in
|
||||
addition to the required `presence` key containing the current presence
|
||||
state of the user.
|
||||
- an `m.presence` presence status update is sent, again containing the
|
||||
new values of the `displayname` and `avatar_url` keys, in addition
|
||||
to the required `presence` key containing the current presence state
|
||||
of the user.
|
||||
|
||||
Both of these should be done automatically by the homeserver when a user
|
||||
successfully changes their display name or avatar URL fields.
|
||||
|
|
|
|||
|
|
@ -1479,43 +1479,6 @@ potential new key backup algorithm version that would fix this issue.
|
|||
|
||||
{{% http-api spec="client-server" api="key_backup" %}}
|
||||
|
||||
###### Key backup enabled preference
|
||||
|
||||
{{% added-in v="1.19" %}}
|
||||
|
||||
This enables clients to track a user's preference about enabling or
|
||||
disabling [server-side backups of room keys](#server-side-key-backups). The data
|
||||
is stored in the [`m.key_backup`](#mkey_backup) global
|
||||
[account data](#client-config).
|
||||
|
||||
{{% event event="m.key_backup" %}}
|
||||
|
||||
When a user signs in to a client which supports encryption and key backup:
|
||||
|
||||
* If this event type exists in account data and contains the specified property
|
||||
in the correct format, clients which support key backup MUST take account of
|
||||
its contents in their behaviour. For example, clients may automatically turn
|
||||
on/off key backup based on the property, or prompt the user, using the
|
||||
property value as a default. (Because this property is server-controlled,
|
||||
clients may wish to confirm the user's intention.)
|
||||
|
||||
* If this event type does not exist in account data, or if it does not contain
|
||||
the `enabled` property, or if the value of `enabled` is not a boolean value,
|
||||
clients MUST ignore the existing value and MAY decide whether or not to
|
||||
perform key backup, possibly based on user input.
|
||||
|
||||
If the user turns on key backups, clients MUST set this event type in account
|
||||
data, to `"enabled": true`.
|
||||
|
||||
If the user turns off key backups, clients MUST set this event type in account
|
||||
data, to `"enabled": false`.
|
||||
|
||||
Clients are not required to monitor the `m.key_backup` account data actively.
|
||||
Clients MAY monitor the setting but should be aware that changing this setting
|
||||
without user interaction based on choices made in a different client (or a
|
||||
compromised homeserver) may cause unforeseen security problems or simply be
|
||||
unexpected by users.
|
||||
|
||||
##### Key exports
|
||||
|
||||
Keys can be manually exported from one device to an encrypted file,
|
||||
|
|
|
|||
|
|
@ -20,10 +20,6 @@ old room. Another approach may be to virtually merge the rooms such that
|
|||
the old room's timeline seamlessly continues into the new timeline
|
||||
without the user having to jump between the rooms.
|
||||
|
||||
When joining a room using the room ID in an `m.room.tombstone` event or
|
||||
`predecessor` field on `m.room.create`, clients SHOULD parse the event
|
||||
`sender` and use the resulting server name as a `via` parameter.
|
||||
|
||||
{{% http-api spec="client-server" api="room_upgrades" %}}
|
||||
|
||||
#### Server behaviour
|
||||
|
|
|
|||
|
|
@ -374,5 +374,5 @@ Version 2.0 http://www.apache.org/licenses/LICENSE-2.0.
|
|||
[AES-256]: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
|
||||
[CBC]: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
|
||||
[PKCS#7]: https://tools.ietf.org/html/rfc2315
|
||||
[Olm]: /olm-megolm/olm/
|
||||
[Olm]: https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/olm.md
|
||||
[Protocol Buffers encoding]: https://developers.google.com/protocol-buffers/docs/encoding
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ The available room versions are:
|
|||
- [Version 5](/rooms/v5) - **Stable**. Introduces enforcement of
|
||||
signing key validity periods.
|
||||
- [Version 6](/rooms/v6) - **Stable**. Alters several
|
||||
authorisation rules for events.
|
||||
authorization rules for events.
|
||||
- [Version 7](/rooms/v7) - **Stable**. Introduces knocking.
|
||||
- [Version 8](/rooms/v8) - **Stable**. Adds a join rule to allow members
|
||||
of another room to join without invite.
|
||||
|
|
@ -85,7 +85,7 @@ The available room versions are:
|
|||
|
||||
Room versions are used to change properties of rooms that may not be
|
||||
compatible with other servers. For example, changing the rules for event
|
||||
authorisation would cause older servers to potentially end up in a
|
||||
authorization would cause older servers to potentially end up in a
|
||||
split-brain situation due to not understanding the new rules.
|
||||
|
||||
A room version is defined as a string of characters which MUST NOT
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -123,11 +123,11 @@ events: for events *x* and *y*, *x* < *y* if
|
|||
The *iterative auth checks algorithm* takes as input an initial room
|
||||
state and a sorted list of state events, and constructs a new room state
|
||||
by iterating through the event list and applying the state event to the
|
||||
room state if the state event is allowed by the [authorisation
|
||||
rules](/server-server-api#authorisation-rules).
|
||||
If the state event is not allowed by the authorisation rules, then the
|
||||
room state if the state event is allowed by the [authorization
|
||||
rules](/server-server-api#authorization-rules).
|
||||
If the state event is not allowed by the authorization rules, then the
|
||||
event is ignored. If a `(event_type, state_key)` key that is required
|
||||
for checking the authorisation rules is not present in the state, then
|
||||
for checking the authorization rules is not present in the state, then
|
||||
the appropriate state event from the event's `auth_events` is used if
|
||||
the auth event is not rejected.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ in the same respect, so does not need a signature from that server.
|
|||
The event must still be signed by the server denoted by the `sender` property,
|
||||
however.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
---
|
||||
{{% added-in v=3 %}} In room versions 1 and 2, redactions were
|
||||
explicitly part of the [authorisation rules](/rooms/v1/#authorisation-rules)
|
||||
explicitly part of the [authorization rules](/rooms/v1/#authorization-rules)
|
||||
under Rule 11. As of room version 3, these conditions no longer exist as
|
||||
represented by [this version's authorisation rules](#authorisation-rules).
|
||||
represented by [this version's authorization rules](#authorization-rules).
|
||||
|
||||
While redactions are always accepted by the authorisation rules for
|
||||
While redactions are always accepted by the authorization rules for
|
||||
events, they should not be sent to clients until both the redaction
|
||||
event and the event the redaction affects have been received, and can
|
||||
be validated. If both events are valid and have been seen by the server,
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ Events in version 1 rooms have the following structure:
|
|||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v1-auth-rules" %}}
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ results of the resolution so far.
|
|||
`sha1(event_id)`.
|
||||
- Add the first event in the list to *R*.
|
||||
- For each subsequent event in the list, check that the event
|
||||
would be allowed by the authorisation rules for a room in state
|
||||
would be allowed by the authorization rules for a room in state
|
||||
*R*. If the event would be allowed, then update *R* with the
|
||||
event and continue with the next event in the list. If it would
|
||||
not be allowed, stop and continue below with `m.room.join_rules`
|
||||
|
|
@ -115,7 +115,7 @@ results of the resolution so far.
|
|||
events.
|
||||
- Repeat the above process for conflicts between `m.room.member`
|
||||
events.
|
||||
- No other events affect the authorisation rules, so for all other
|
||||
- No other events affect the authorization rules, so for all other
|
||||
conflicts, just pick the event with the highest depth and lowest
|
||||
`sha1(event_id)` that passes authentication in *R* and add it to
|
||||
*R*.
|
||||
|
|
|
|||
|
|
@ -71,13 +71,13 @@ power levels could be represented as strings for backwards compatibility.
|
|||
|
||||
This backwards compatibility is removed in this room version - power levels MUST NOT
|
||||
be represented as strings within this room version. Power levels which are not
|
||||
correctly structured are rejected under the authorisation rules below.
|
||||
correctly structured are rejected under the authorization rules below.
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -80,11 +80,11 @@ For improved compatibility with newer clients, servers should add a `redacts` pr
|
|||
to the `content` of `m.room.redaction` events in *older* room versions when serving
|
||||
such events over the Client-Server API.
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -43,11 +43,11 @@ Room version 12 is based upon room version 11 with the following considerations.
|
|||
|
||||
{{% rver-fragment name="v12-event-format" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
@ -267,7 +267,7 @@ algorithm found in [room version 2](/rooms/v2) with the following modifications:
|
|||
now starts with an *empty* state map instead of the unconflicted state map.
|
||||
|
||||
2. A new [definition](#definitions) for *conflicted state subgraph* has been added
|
||||
which describes events that are required to authorise events during iterative
|
||||
which describes events that are required to authorize events during iterative
|
||||
auth checks.
|
||||
|
||||
3. To ensure the new conflicted state subgraph is actually referenced, the definition
|
||||
|
|
@ -405,11 +405,11 @@ events: for events *x* and *y*, *x* < *y* if
|
|||
The *iterative auth checks algorithm* takes as input an initial room
|
||||
state and a sorted list of state events, and constructs a new room state
|
||||
by iterating through the event list and applying the state event to the
|
||||
room state if the state event is allowed by the [authorisation
|
||||
rules](/server-server-api#authorisation-rules).
|
||||
If the state event is not allowed by the authorisation rules, then the
|
||||
room state if the state event is allowed by the [authorization
|
||||
rules](/server-server-api#authorization-rules).
|
||||
If the state event is not allowed by the authorization rules, then the
|
||||
event is ignored. If a `(event_type, state_key)` key that is required
|
||||
for checking the authorisation rules is not present in the state, then
|
||||
for checking the authorization rules is not present in the state, then
|
||||
the appropriate state event from the event's `auth_events` is used if
|
||||
the auth event is not rejected.
|
||||
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@ Events in rooms of this version have the following structure:
|
|||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v1-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -89,7 +89,7 @@ The complete structure of a event in a v3 room is shown below.
|
|||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v=3 %}} `m.room.redaction` events are subject to auth rules in
|
||||
|
|
|
|||
|
|
@ -78,7 +78,7 @@ the changes in this room version.
|
|||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v3-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -60,7 +60,7 @@ completeness.
|
|||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v3-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ version: 6
|
|||
---
|
||||
|
||||
This room version builds on [version 5](/rooms/v5) while changing various
|
||||
authorisation rules performed on events.
|
||||
authorization rules performed on events.
|
||||
|
||||
## Client considerations
|
||||
|
||||
|
|
@ -47,20 +47,20 @@ no longer be formatted as floats.
|
|||
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% added-in v=6 %}} Rule 4, which related specifically to events
|
||||
of type `m.room.aliases`, is removed. `m.room.aliases` events must still pass
|
||||
authorisation checks relating to state events.
|
||||
authorization checks relating to state events.
|
||||
|
||||
{{% added-in v=6 %}} Additionally, the authorisation rules for events of
|
||||
{{% added-in v=6 %}} Additionally, the authorization rules for events of
|
||||
type `m.room.power_levels` now include a `notifications` property under
|
||||
`content`. This updates rules 10.4 and 10.5 (now 9.4 and 9.5), which checked
|
||||
the `events` property.
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -27,18 +27,18 @@ regarding client considerations is the resource that Client-Server API
|
|||
use cases should reference.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
Room version 7 adds new authorisation rules for events to support knocking.
|
||||
[Room version 6](/rooms/v6) has details of other authorisation rule changes,
|
||||
Room version 7 adds new authorization rules for events to support knocking.
|
||||
[Room version 6](/rooms/v6) has details of other authorization rule changes,
|
||||
as do the versions v6 is based upon.
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% added-in v=7 %}} For checks performed upon `m.room.member` events, a
|
||||
new point for `membership=knock` is added.
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@ Room version 8 adds a new join rule to allow members of a room to join another
|
|||
room without invite. Otherwise, the room version inherits all properties of
|
||||
[Room version 7](/rooms/v7).
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% added-in v=8 %}} For checks performed upon `m.room.member` events, new
|
||||
points for handling `content.join_authorised_via_users_server` are added (Rule 4.2
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@ completeness.
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v8-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ description: |
|
|||
real-time, retrieve historic messages, and query profile or presence
|
||||
information about users on other servers. The APIs are implemented over HTTPS,
|
||||
with authentication provided by public key signatures both at the TLS
|
||||
transport layer and in HTTP `Authorization` headers.
|
||||
transport layer and in HTTP Authorization headers.
|
||||
|
||||
There are three main kinds of communication that occur between
|
||||
homeservers:
|
||||
|
|
@ -279,7 +279,7 @@ Every HTTP request made by a homeserver is authenticated using public
|
|||
key digital signatures. The request method, target and body are signed
|
||||
by wrapping them in a JSON object and signing it using the [JSON signing
|
||||
algorithm](/appendices#signing-json). The resulting signatures are added
|
||||
as an `Authorization` header with an auth scheme of `X-Matrix`. Note that
|
||||
as an Authorization header with an auth scheme of `X-Matrix`. Note that
|
||||
the target field should include the full path starting with `/_matrix/...`,
|
||||
including the `?` and any query parameters if present, but should not
|
||||
include the leading `https:`, nor the destination server's hostname.
|
||||
|
|
@ -307,7 +307,7 @@ section](#resolving-server-names) above do not affect these - the server
|
|||
names from before delegation would take place are used. This same
|
||||
condition applies throughout the request signing process.
|
||||
|
||||
Step 2 add `Authorization` header:
|
||||
Step 2 add Authorization header:
|
||||
|
||||
POST /target HTTP/1.1
|
||||
Authorization: X-Matrix origin="origin.hs.example.com",destination="destination.hs.example.com",key="ed25519:key1",sig="ABCDEF..."
|
||||
|
|
@ -346,9 +346,9 @@ def authorization_headers(origin_name, origin_signing_key,
|
|||
return ("Authorization", authorization_headers[0])
|
||||
```
|
||||
|
||||
The format of the `Authorization` header is given in
|
||||
The format of the Authorization header is given in
|
||||
[Section 11.4 of RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#section-11.4). In
|
||||
summary, the header begins with authorisation scheme `X-Matrix`, followed by one
|
||||
summary, the header begins with authorization scheme `X-Matrix`, followed by one
|
||||
or more spaces, followed by a comma-separated list of parameters written as
|
||||
name=value pairs. Zero or more spaces and tabs around each comma are allowed.
|
||||
The names are case insensitive and order does not matter. The
|
||||
|
|
@ -369,7 +369,7 @@ For compatibility with older servers, the sender should
|
|||
For compatibility with older servers, the recipient should allow colons to be
|
||||
included in values without requiring the value to be enclosed in quotes.
|
||||
|
||||
The authorisation parameters to include are:
|
||||
The authorization parameters to include are:
|
||||
|
||||
- `origin`: the server name of the sending server. This is the same as the
|
||||
`origin` field from JSON described in step 1.
|
||||
|
|
@ -378,8 +378,8 @@ The authorisation parameters to include are:
|
|||
in step 1. For compatibility with older servers, recipients should accept
|
||||
requests without this parameter, but MUST always send it. If this property
|
||||
is included, but the value does not match the receiving server's name, the
|
||||
receiving server must deny the request with an HTTP status code `401
|
||||
Unauthorized`.
|
||||
receiving server must deny the request with an HTTP status code 401
|
||||
Unauthorized.
|
||||
- `key`: the ID, including the algorithm name, of the sending server's key used
|
||||
to sign the request.
|
||||
- `signature`: the signature of the JSON as calculated in step 1.
|
||||
|
|
@ -467,11 +467,11 @@ server must ensure that the event:
|
|||
2. Passes signature checks, otherwise it is dropped.
|
||||
3. Passes hash checks, otherwise it is redacted before being processed
|
||||
further.
|
||||
4. Passes authorisation rules based on the event's auth events,
|
||||
4. Passes authorization rules based on the event's auth events,
|
||||
otherwise it is rejected.
|
||||
5. Passes authorisation rules based on the state before the event,
|
||||
5. Passes authorization rules based on the state before the event,
|
||||
otherwise it is rejected.
|
||||
6. Passes authorisation rules based on the current state of the room,
|
||||
6. Passes authorization rules based on the current state of the room,
|
||||
otherwise it is "soft failed".
|
||||
7. {{% added-in v="1.18" %}} Is [validated](#validating-policy-server-signatures)
|
||||
by the Policy Server, if the room is [using a Policy Server](#determining-if-a-policy-server-is-enabled-in-a-room),
|
||||
|
|
@ -516,9 +516,9 @@ and must never populate the default power levels in a room as string values.
|
|||
See the [room version specification](/rooms) for more information.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
#### Authorisation rules
|
||||
#### Authorization rules
|
||||
|
||||
The rules governing whether an event is authorised depends on a set of
|
||||
The rules governing whether an event is authorized depends on a set of
|
||||
state. A given event is checked multiple times against different sets of
|
||||
state, as specified above. Each room version can have a different
|
||||
algorithm for how the rules work, and which rules are applied. For more
|
||||
|
|
@ -697,9 +697,9 @@ then any new event `D'` will not reference `C`:
|
|||
Events can also be soft failed if they fail [Policy Server checks](#validating-policy-server-signatures).
|
||||
{{% /boxes/note %}}
|
||||
|
||||
#### Retrieving event authorisation information
|
||||
#### Retrieving event authorization information
|
||||
|
||||
The homeserver may be missing event authorisation information, or wish
|
||||
The homeserver may be missing event authorization information, or wish
|
||||
to check with other servers to ensure it is receiving the correct auth
|
||||
chain. These APIs give the homeserver an avenue for getting the
|
||||
information it needs.
|
||||
|
|
@ -1484,30 +1484,34 @@ the Policy Server for a signature too.
|
|||
When a server receives an event over federation from another server, the
|
||||
receiving server should check the hashes and signatures on that event.
|
||||
|
||||
First the signatures are checked. The event is redacted following the
|
||||
[redaction algorithm](/client-server-api#redactions), and
|
||||
the resultant object is checked for signatures from the originating
|
||||
First the signature is checked. The event is redacted following the
|
||||
[redaction
|
||||
algorithm](/client-server-api#redactions), and
|
||||
the resultant object is checked for a signature from the originating
|
||||
server, following the algorithm described in [Checking for a
|
||||
signature](/appendices#checking-for-a-signature). Note that this
|
||||
step should succeed whether we have been sent the full event or a
|
||||
redacted copy.
|
||||
|
||||
For room versions 3 and later, unless the event is a 3rd party invite, only the
|
||||
signature(s) from the originating server (the server the `sender` belongs to)
|
||||
are required for verification. Room versions 1 and 2 also require that a
|
||||
signature is present from the domain in the `event_id`, if it differs from the
|
||||
originating server. If a signature is from an unknown or expired key, it is
|
||||
skipped.
|
||||
The signatures expected on an event are:
|
||||
|
||||
If the event is a 3rd party invite, the sender must already match the 3rd party
|
||||
invite, and the server which actually sends the event may be a different
|
||||
server.
|
||||
- The `sender`'s server, unless the invite was created as a result of
|
||||
3rd party invite. The sender must already match the 3rd party
|
||||
invite, and the server which actually sends the event may be a
|
||||
different server.
|
||||
- For room versions 1 and 2, the server which created the `event_id`.
|
||||
Other room versions do not track the `event_id` over federation and
|
||||
therefore do not need a signature from those servers.
|
||||
|
||||
Only signatures from known server keys are validated here. Any unknown keys are ignored.
|
||||
In particular, the [policy server key](#validating-policy-server-signatures) is not
|
||||
expected to be published and therefore should be skipped at this stage.
|
||||
Additionally, any keys that are known to have expired prior to the event's
|
||||
`origin_server_ts` are ignored.
|
||||
If the signature is found to be valid, the expected content hash is
|
||||
calculated as described below. The content hash in the `hashes` property
|
||||
of the received event is base64-decoded, and the two are compared for
|
||||
equality.
|
||||
|
||||
If the hash check fails, then it is assumed that this is because we have
|
||||
only been given a redacted version of the event. To enforce this, the
|
||||
receiving server should use the redacted copy it calculated rather than
|
||||
the full copy it received.
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.18" %}}
|
||||
|
|
@ -1515,16 +1519,6 @@ Events sent in rooms with [Policy Servers](#policy-servers) have [additional](#v
|
|||
signature validation requirements.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
If all signatures from known unexpired keys from the originating server(s) are
|
||||
found to be valid, the expected content hash is calculated as described below.
|
||||
The content hash in the `hashes` property of the received event is base64-decoded,
|
||||
and the two are compared for equality.
|
||||
|
||||
If the hash check fails, then it is assumed that this is because we have
|
||||
only been given a redacted version of the event. To enforce this, the
|
||||
receiving server should use the redacted copy it calculated rather than
|
||||
the full copy it received.
|
||||
|
||||
### Calculating the reference hash for an event
|
||||
|
||||
The *reference hash* of an event covers the essential fields of an
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to set account data for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -83,7 +83,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorised to modify this user's account
|
||||
The access token provided is not authorized to modify this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -126,7 +126,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to get account data for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -151,7 +151,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorised to retrieve this user's account
|
||||
The access token provided is not authorized to retrieve this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -196,7 +196,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to set account data for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -253,7 +253,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorised to modify this user's account
|
||||
The access token provided is not authorized to modify this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -296,7 +296,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to get account data for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -341,7 +341,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorised to retrieve this user's account
|
||||
The access token provided is not authorized to retrieve this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
|
|||
|
|
@ -116,7 +116,7 @@ paths:
|
|||
|
||||
The user calling this endpoint MUST be a server admin.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
In order to prevent user enumeration, servers MUST ensure that authorization is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: getAdminSuspendUser
|
||||
security:
|
||||
|
|
@ -204,7 +204,7 @@ paths:
|
|||
is allowed to suspend other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
|
||||
endpoint prior to using this endpoint.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
In order to prevent user enumeration, servers MUST ensure that authorization is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: setAdminSuspendUser
|
||||
security:
|
||||
|
|
@ -309,7 +309,7 @@ paths:
|
|||
|
||||
The user calling this endpoint MUST be a server admin.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
In order to prevent user enumeration, servers MUST ensure that authorization is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: getAdminLockUser
|
||||
security:
|
||||
|
|
@ -396,7 +396,7 @@ paths:
|
|||
is allowed to lock other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
|
||||
endpoint prior to using this endpoint.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
In order to prevent user enumeration, servers MUST ensure that authorization is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: setAdminLockUser
|
||||
security:
|
||||
|
|
|
|||
|
|
@ -159,7 +159,7 @@ paths:
|
|||
"403":
|
||||
description: |-
|
||||
The public key of one of the keys is the same as one of the user\'s
|
||||
device IDs, or the request is not authorised for any other reason.
|
||||
device IDs, or the request is not authorized for any other reason.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
|
|||
|
|
@ -24,9 +24,8 @@ allOf:
|
|||
room_id:
|
||||
description: The ID of the room associated with this event.
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
example: '!jEsUZKDJdhlrceRyVU:example.org'
|
||||
|
||||
unsigned:
|
||||
properties:
|
||||
redacted_because:
|
||||
|
|
@ -44,6 +43,6 @@ allOf:
|
|||
"unsigned": {
|
||||
"age": 1257,
|
||||
}
|
||||
}
|
||||
}
|
||||
required:
|
||||
- room_id
|
||||
|
|
|
|||
|
|
@ -28,8 +28,6 @@ properties:
|
|||
event_id:
|
||||
description: The globally unique identifier for this event.
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
example: '$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45'
|
||||
type:
|
||||
description: The type of the event.
|
||||
|
|
@ -49,8 +47,6 @@ properties:
|
|||
sender:
|
||||
description: Contains the fully-qualified ID of the user who sent this event.
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
example: "@example:example.org"
|
||||
origin_server_ts:
|
||||
description: |-
|
||||
|
|
@ -105,10 +101,9 @@ properties:
|
|||
type: string
|
||||
prev_content:
|
||||
description: |
|
||||
The `content` of the previous state event that was replaced by this event.
|
||||
This field is generated by the local homeserver, and is only returned if
|
||||
the event is a state event, and the client has permission to see the
|
||||
previous event.
|
||||
The previous `content` for this event. This field is generated
|
||||
by the local homeserver, and is only returned if the event is a state event,
|
||||
and the client has permission to see the previous content.
|
||||
x-changedInMatrixVersion:
|
||||
"1.2": |
|
||||
Previously, this field was specified at the top level of returned
|
||||
|
|
@ -118,13 +113,6 @@ properties:
|
|||
this.
|
||||
title: EventContent
|
||||
type: object
|
||||
replaces_state:
|
||||
description: |
|
||||
The event ID of the state event replaced by this event. This field is generated
|
||||
by the local homeserver, and is only returned if the event is a state event.
|
||||
Unlike `prev_content`, this field is included regardless of history visibility.
|
||||
type: string
|
||||
x-addedInMatrixVersion: "1.19"
|
||||
membership:
|
||||
description: |
|
||||
The room membership of the user making the request, at the time of the event.
|
||||
|
|
|
|||
|
|
@ -26,8 +26,6 @@ properties:
|
|||
`senders` filter.
|
||||
items:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
type: array
|
||||
not_types:
|
||||
description: A list of event types to exclude. If this list is absent then no
|
||||
|
|
@ -42,8 +40,6 @@ properties:
|
|||
senders are included.
|
||||
items:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
type: array
|
||||
types:
|
||||
description: A list of event types to include. If this list is absent then all
|
||||
|
|
|
|||
|
|
@ -39,7 +39,5 @@ properties:
|
|||
such.
|
||||
event_id:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
description: The event ID of the event that this event relates to.
|
||||
required: ['rel_type', 'event_id']
|
||||
|
|
|
|||
|
|
@ -43,16 +43,12 @@ allOf:
|
|||
filter.
|
||||
items:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
type: array
|
||||
rooms:
|
||||
description: A list of room IDs to include. If this list is absent then all rooms
|
||||
are included.
|
||||
items:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
type: array
|
||||
contains_url:
|
||||
type: boolean
|
||||
|
|
|
|||
|
|
@ -50,8 +50,6 @@ properties:
|
|||
`state`, `timeline` or `account_data`
|
||||
items:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
type: array
|
||||
rooms:
|
||||
description: A list of room IDs to include. If this list is absent then all rooms
|
||||
|
|
@ -59,8 +57,6 @@ properties:
|
|||
`state`, `timeline` or `account_data`
|
||||
items:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
type: array
|
||||
ephemeral:
|
||||
allOf:
|
||||
|
|
|
|||
|
|
@ -32,12 +32,10 @@ paths:
|
|||
name: userId
|
||||
required: true
|
||||
description: The id of the user uploading the filter. The access token must be
|
||||
authorised to make requests for this user id.
|
||||
authorized to make requests for this user id.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -132,8 +130,6 @@ paths:
|
|||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
- in: path
|
||||
name: filterId
|
||||
description: The filter ID to download.
|
||||
|
|
|
|||
|
|
@ -97,7 +97,7 @@ paths:
|
|||
summary: Authenticates the user.
|
||||
description: |-
|
||||
Authenticates the user, and issues an access token they can
|
||||
use to authorise themself in subsequent requests.
|
||||
use to authorize themself in subsequent requests.
|
||||
|
||||
If the client does not supply a `device_id`, the server must
|
||||
auto-generate one.
|
||||
|
|
@ -194,7 +194,7 @@ paths:
|
|||
type: string
|
||||
description: |-
|
||||
An access token for the account.
|
||||
This access token can then be used to authorise other requests.
|
||||
This access token can then be used to authorize other requests.
|
||||
refresh_token:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ paths:
|
|||
summary: Invalidates a user access token
|
||||
description: |-
|
||||
Invalidates an existing access token, so that it can no longer be used for
|
||||
authorisation. The device associated with the access token is also deleted.
|
||||
authorization. The device associated with the access token is also deleted.
|
||||
[Device keys](/client-server-api/#device-keys) for the device are deleted alongside the device.
|
||||
operationId: logout
|
||||
security:
|
||||
|
|
@ -42,7 +42,7 @@ paths:
|
|||
summary: Invalidates all access tokens for a user
|
||||
description: |-
|
||||
Invalidates all access tokens for a user, so that they can no longer be used for
|
||||
authorisation. This includes the access token that made this request. All devices
|
||||
authorization. This includes the access token that made this request. All devices
|
||||
for the user are also deleted. [Device keys](/client-server-api/#device-keys) for the device are
|
||||
deleted alongside the device.
|
||||
|
||||
|
|
|
|||
|
|
@ -37,8 +37,6 @@ paths:
|
|||
example: "!636q39766251:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
- in: query
|
||||
name: from
|
||||
x-changedInMatrixVersion:
|
||||
|
|
|
|||
|
|
@ -18,22 +18,22 @@ info:
|
|||
paths:
|
||||
"/auth_metadata":
|
||||
get:
|
||||
summary: Get the OAuth 2.0 authorisation server metadata.
|
||||
summary: Get the OAuth 2.0 authorization server metadata.
|
||||
description: |-
|
||||
Gets the OAuth 2.0 authorisation server metadata, as defined in
|
||||
Gets the OAuth 2.0 authorization server metadata, as defined in
|
||||
[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414), including the
|
||||
endpoint URLs and the supported parameters that can be used by the
|
||||
clients.
|
||||
|
||||
This endpoint definition includes only the fields that are meaningful in
|
||||
the context of the Matrix specification. The full list of possible
|
||||
fields is available in the [OAuth Authorisation Server Metadata
|
||||
fields is available in the [OAuth Authorization Server Metadata
|
||||
registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata),
|
||||
and normative definitions of them are available in their respective
|
||||
RFCs.
|
||||
|
||||
{{% boxes/note %}}
|
||||
The authorisation server metadata is relatively large and may change
|
||||
The authorization server metadata is relatively large and may change
|
||||
over time. Clients should:
|
||||
|
||||
- Cache the metadata appropriately based on HTTP caching headers
|
||||
|
|
@ -42,7 +42,7 @@ paths:
|
|||
operationId: getAuthMetadata
|
||||
responses:
|
||||
"200":
|
||||
description: The OAuth 2.0 authorisation server metadata.
|
||||
description: The OAuth 2.0 authorization server metadata.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -52,7 +52,7 @@ paths:
|
|||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
The authorisation server's issuer identifier, which is a URL that uses the
|
||||
The authorization server's issuer identifier, which is a URL that uses the
|
||||
`https` scheme and has no query or fragment components.
|
||||
|
||||
This is not used in the context of the Matrix specification, but is required
|
||||
|
|
@ -61,7 +61,7 @@ paths:
|
|||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
URL of the authorisation endpoint, necessary to use the authorisation code
|
||||
URL of the authorization endpoint, necessary to use the authorization code
|
||||
grant.
|
||||
token_endpoint:
|
||||
type: string
|
||||
|
|
@ -84,10 +84,10 @@ paths:
|
|||
type: array
|
||||
description: |-
|
||||
List of OAuth 2.0 response type strings that the server supports at the
|
||||
authorisation endpoint.
|
||||
authorization endpoint.
|
||||
|
||||
This array MUST contain at least the `code` value, for clients to be able to
|
||||
use the authorisation code grant.
|
||||
use the authorization code grant.
|
||||
items:
|
||||
type: string
|
||||
description: A response type that the server supports.
|
||||
|
|
@ -98,12 +98,12 @@ paths:
|
|||
endpoint.
|
||||
|
||||
This array MUST contain at least the `authorization_code` and `refresh_token`
|
||||
values, for clients to be able to use the authorisation code grant and refresh
|
||||
values, for clients to be able to use the authorization code grant and refresh
|
||||
token grant, respectively.
|
||||
|
||||
{{% added-in v="1.18" %}} It MAY also contain
|
||||
`urn:ietf:params:oauth:grant-type:device_code` to indicate support for the
|
||||
[device authorisation grant](/client-server-api/#device-authorisation-grant).
|
||||
[device authorization grant](/client-server-api/#device-authorization-grant).
|
||||
items:
|
||||
type: string
|
||||
description: A grant type that the server supports.
|
||||
|
|
@ -111,10 +111,10 @@ paths:
|
|||
type: array
|
||||
description: |-
|
||||
List of OAuth 2.0 response mode strings that the server supports at the
|
||||
authorisation endpoint.
|
||||
authorization endpoint.
|
||||
|
||||
This array MUST contain at least the `query` and `fragment` values, for
|
||||
improved security in the authorisation code grant.
|
||||
improved security in the authorization code grant.
|
||||
items:
|
||||
type: string
|
||||
description: A response mode that the server supports.
|
||||
|
|
@ -122,10 +122,10 @@ paths:
|
|||
type: array
|
||||
description: |-
|
||||
List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods
|
||||
that the server supports at the authorisation endpoint.
|
||||
that the server supports at the authorization endpoint.
|
||||
|
||||
This array MUST contain at least the `S256` value, for improved security in
|
||||
the authorisation code grant.
|
||||
the authorization code grant.
|
||||
items:
|
||||
type: string
|
||||
description: A PKCE code challenge method that the server supports.
|
||||
|
|
@ -133,7 +133,7 @@ paths:
|
|||
type: array
|
||||
description: |-
|
||||
List of OpenID Connect prompt values that the server supports at the
|
||||
authorisation endpoint.
|
||||
authorization endpoint.
|
||||
|
||||
Only the `create` value defined in [Initiating User Registration via OpenID
|
||||
Connect](https://openid.net/specs/openid-connect-prompt-create-1_0.html) is
|
||||
|
|
@ -173,9 +173,9 @@ paths:
|
|||
type: string
|
||||
format: uri
|
||||
description: |-
|
||||
URL of the device authorisation endpoint, as defined in
|
||||
URL of the device authorization endpoint, as defined in
|
||||
[RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), necessary to use
|
||||
the [device authorisation grant](/client-server-api/#device-authorisation-grant).
|
||||
the [device authorization grant](/client-server-api/#device-authorization-grant).
|
||||
required:
|
||||
- issuer
|
||||
- authorization_endpoint
|
||||
|
|
|
|||
|
|
@ -148,8 +148,6 @@ paths:
|
|||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
description: The ID of this room.
|
||||
membership:
|
||||
type: string
|
||||
|
|
@ -339,8 +337,6 @@ paths:
|
|||
example: $asfDuShaf7Gafaw:matrix.org
|
||||
schema:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
responses:
|
||||
"200":
|
||||
description: The full event.
|
||||
|
|
|
|||
|
|
@ -46,8 +46,6 @@ paths:
|
|||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
- in: path
|
||||
name: keyName
|
||||
description: The name of the profile field to set. This MUST be either
|
||||
|
|
@ -71,11 +69,11 @@ paths:
|
|||
description: |
|
||||
An object which contains exactly one property. The key
|
||||
of that property MUST match the `keyName` specified in the URL.
|
||||
|
||||
For `avatar_url`, the value MUST be an MXC URI string.
|
||||
|
||||
|
||||
For `avatar_url`, the value MUST be an MXC URI string.
|
||||
|
||||
For `displayname`, the value MUST be a string.
|
||||
|
||||
|
||||
For `m.tz`, the value MUST be a valid identifier from the [IANA Time Zone Database](https://www.iana.org/time-zones).
|
||||
Servers MAY choose to validate the value. Clients MUST expect unknown or invalid
|
||||
values.
|
||||
|
|
@ -98,7 +96,7 @@ paths:
|
|||
description: |
|
||||
The input was invalid in some way. This can include one
|
||||
of the following error codes:
|
||||
|
||||
|
||||
- `M_BAD_JSON`: The provided value is not valid JSON.
|
||||
- `M_MISSING_PARAM`: The required `keyName` property is
|
||||
missing from the request body.
|
||||
|
|
@ -160,8 +158,6 @@ paths:
|
|||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
- in: path
|
||||
name: keyName
|
||||
description: The name of the profile field to retrieve.
|
||||
|
|
@ -220,8 +216,6 @@ paths:
|
|||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
- in: path
|
||||
name: keyName
|
||||
description: The name of the profile field to delete.
|
||||
|
|
@ -292,8 +286,6 @@ paths:
|
|||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
responses:
|
||||
"200":
|
||||
description: The profile information for this user.
|
||||
|
|
|
|||
|
|
@ -43,17 +43,13 @@ paths:
|
|||
example: "!637q39766251:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
- in: path
|
||||
name: eventId
|
||||
description: The ID of the event to redact.
|
||||
description: The ID of the event to redact
|
||||
required: true
|
||||
example: $bai2b1i9:matrix.org
|
||||
example: bai2b1i9:matrix.org
|
||||
schema:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
- in: path
|
||||
name: txnId
|
||||
description: |-
|
||||
|
|
@ -86,8 +82,6 @@ paths:
|
|||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
description: A unique identifier for the event.
|
||||
examples:
|
||||
response:
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ paths:
|
|||
- `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
|
||||
|
||||
If registration is successful, this endpoint will issue an access token
|
||||
the client can use to authorise itself in subsequent requests.
|
||||
the client can use to authorize itself in subsequent requests.
|
||||
|
||||
If the client does not supply a `device_id`, the server must
|
||||
auto-generate one.
|
||||
|
|
@ -167,7 +167,7 @@ paths:
|
|||
type: string
|
||||
description: |-
|
||||
An access token for the account.
|
||||
This access token can then be used to authorise other requests.
|
||||
This access token can then be used to authorize other requests.
|
||||
Required if the `inhibit_login` option is false.
|
||||
refresh_token:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -233,8 +233,6 @@ components:
|
|||
example: "!636q39766251:matrix.org"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
eventId:
|
||||
in: path
|
||||
name: eventId
|
||||
|
|
@ -243,8 +241,6 @@ components:
|
|||
example: $asfDuShaf7Gafaw
|
||||
schema:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
from:
|
||||
in: query
|
||||
name: from
|
||||
|
|
|
|||
|
|
@ -56,8 +56,6 @@ paths:
|
|||
example: "!636q39766251:matrix.org"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
- in: query
|
||||
name: ts
|
||||
description: |-
|
||||
|
|
@ -88,8 +86,6 @@ paths:
|
|||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
description: The ID of the event found
|
||||
origin_server_ts:
|
||||
type: integer
|
||||
|
|
|
|||
|
|
@ -27,8 +27,6 @@ paths:
|
|||
example: "!636q39766251:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
responses:
|
||||
"200":
|
||||
description: The current state of the room
|
||||
|
|
@ -40,8 +38,6 @@ paths:
|
|||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
description: The ID of this room.
|
||||
membership:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -49,8 +49,6 @@ paths:
|
|||
example: "!636q39766251:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
- in: path
|
||||
name: eventType
|
||||
description: The type of event to send.
|
||||
|
|
@ -88,8 +86,6 @@ paths:
|
|||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
description: A unique identifier for the event.
|
||||
required:
|
||||
- event_id
|
||||
|
|
|
|||
|
|
@ -49,8 +49,6 @@ paths:
|
|||
example: "!636q39766251:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
- in: path
|
||||
name: eventType
|
||||
description: The type of event to send.
|
||||
|
|
@ -88,8 +86,6 @@ paths:
|
|||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
description: A unique identifier for the event.
|
||||
required:
|
||||
- event_id
|
||||
|
|
|
|||
|
|
@ -34,8 +34,6 @@ paths:
|
|||
example: "!636q39766251:matrix.org"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
- in: path
|
||||
name: eventId
|
||||
description: The event ID to get.
|
||||
|
|
@ -43,8 +41,6 @@ paths:
|
|||
example: $asfDuShaf7Gafaw:matrix.org
|
||||
schema:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
responses:
|
||||
"200":
|
||||
description: The full event.
|
||||
|
|
@ -93,8 +89,6 @@ paths:
|
|||
example: "!636q39766251:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
- in: path
|
||||
name: eventType
|
||||
description: The type of state to look up.
|
||||
|
|
@ -164,8 +158,6 @@ paths:
|
|||
example: "!636q39766251:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
responses:
|
||||
"200":
|
||||
description: The current state of the room
|
||||
|
|
@ -219,8 +211,6 @@ paths:
|
|||
example: "!636q39766251:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
- in: query
|
||||
name: at
|
||||
description: |-
|
||||
|
|
@ -315,8 +305,6 @@ paths:
|
|||
example: "!636q39766251:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
|
|
|
|||
|
|
@ -209,8 +209,6 @@ paths:
|
|||
field may be omitted.
|
||||
items:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
m.joined_member_count:
|
||||
type: integer
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The id of the user to get tags for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -83,7 +83,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The id of the user to add a tag for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -133,7 +133,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The id of the user to remove a tag for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ paths:
|
|||
`public` [join rule](#mroomjoin_rules)
|
||||
- users who are joined to rooms known to the homeserver that have a
|
||||
`world_readable` [history visibility](#room-history-visibility)
|
||||
|
||||
|
||||
The search MUST consider local users to the homeserver, and SHOULD
|
||||
query remote users as part of the search.
|
||||
|
||||
|
|
@ -82,8 +82,6 @@ paths:
|
|||
type: string
|
||||
example: "@foo:bar.com"
|
||||
description: The user's matrix user ID.
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
display_name:
|
||||
type: string
|
||||
example: Foo
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ properties:
|
|||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the authorisation events that would
|
||||
Event IDs for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ allOf:
|
|||
auth_events:
|
||||
type: array
|
||||
description: |-
|
||||
Event IDs and reference hashes for the authorisation events that would
|
||||
Event IDs and reference hashes for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ allOf:
|
|||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the authorisation events that would
|
||||
Event IDs for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@
|
|||
# limitations under the License.
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: Matrix Federation Event Authorisation API
|
||||
title: Matrix Federation Event Authorization API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
"/event_auth/{roomId}/{eventId}":
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ paths:
|
|||
"200":
|
||||
description: |-
|
||||
The fully resolved state for the room, prior to considering any state
|
||||
changes induced by the requested event. Includes the authorisation
|
||||
changes induced by the requested event. Includes the authorization
|
||||
chain for the events.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -52,8 +52,8 @@ paths:
|
|||
auth_chain:
|
||||
type: array
|
||||
description: |-
|
||||
The full set of authorisation events that make up the state
|
||||
of the room, and their authorisation events, recursively. Note that
|
||||
The full set of authorization events that make up the state
|
||||
of the room, and their authorization events, recursively. Note that
|
||||
events have a different format depending on the room version -
|
||||
check the [room version specification](/rooms) for precise event formats.
|
||||
items:
|
||||
|
|
@ -114,7 +114,7 @@ paths:
|
|||
"200":
|
||||
description: |-
|
||||
The fully resolved state for the room, prior to considering any state
|
||||
changes induced by the requested event. Includes the authorisation
|
||||
changes induced by the requested event. Includes the authorization
|
||||
chain for the events.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -124,8 +124,8 @@ paths:
|
|||
auth_chain_ids:
|
||||
type: array
|
||||
description: |-
|
||||
The full set of authorisation events that make up the state
|
||||
of the room, and their authorisation events, recursively.
|
||||
The full set of authorization events that make up the state
|
||||
of the room, and their authorization events, recursively.
|
||||
items:
|
||||
type: string
|
||||
example:
|
||||
|
|
|
|||
|
|
@ -137,7 +137,7 @@ paths:
|
|||
}
|
||||
}
|
||||
"403":
|
||||
description: The request is not authorised. This could mean that the user is not
|
||||
description: The request is not authorized. This could mean that the user is not
|
||||
in the room.
|
||||
content:
|
||||
application/json:
|
||||
|
|
|
|||
|
|
@ -111,26 +111,22 @@ paths:
|
|||
summary: Query for profile information about a given user
|
||||
description: |-
|
||||
Performs a query to get profile information, such as a display name or avatar,
|
||||
for a given user. Homeservers MUST only query profiles for users that belong
|
||||
for a given user. Homeservers should only query profiles for users that belong
|
||||
to the target server (identified by the [server name](/appendices/#server-name)
|
||||
in the user ID).
|
||||
|
||||
Responding servers MAY:
|
||||
- Include arbitrary key/value pairs in the profile in addition to the
|
||||
specified pairs.
|
||||
- Deny profile look-up over federation by responding with 403 and an error code of
|
||||
`M_FORBIDDEN`.
|
||||
- Omit certain key/value pairs in the response.
|
||||
|
||||
Requesting servers MAY wish to cache the response to this query to avoid requesting the
|
||||
Servers may wish to cache the response to this query to avoid requesting the
|
||||
information too often.
|
||||
|
||||
Servers MAY deny profile look-up over federation by responding with 403 and an
|
||||
error code of `M_FORBIDDEN`.
|
||||
operationId: queryProfile
|
||||
security:
|
||||
- signedRequest: []
|
||||
parameters:
|
||||
- in: query
|
||||
name: user_id
|
||||
description: The user ID to query. MUST be a user local to the receiving homeserver.
|
||||
description: The user ID to query. Must be a user local to the receiving homeserver.
|
||||
required: true
|
||||
example: "@someone:example.org"
|
||||
schema:
|
||||
|
|
@ -138,27 +134,24 @@ paths:
|
|||
- in: query
|
||||
name: field
|
||||
description: |-
|
||||
The field of the profile to query. If specified, the server MUST only return the
|
||||
given field in the response. If not specified, the server MUST return the full,
|
||||
public, profile for the user.
|
||||
|
||||
Defined values are `displayname`, `avatar_url` and `m.tz`. In addition to these
|
||||
servers MAY allow users to set additional key/value pairs.
|
||||
The field to query. If specified, the server will only return the given field
|
||||
in the response. If not specified, the server will return the full profile for
|
||||
the user.
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
- displayname
|
||||
- avatar_url
|
||||
responses:
|
||||
"200":
|
||||
description: |-
|
||||
The profile for the user. If a `field` is specified in the request, the response
|
||||
MUST only include the specified `field`. If no `field` was specified, the response
|
||||
SHOULD include all of the fields of the user's profile that can be made public, such
|
||||
as the display name and avatar.
|
||||
|
||||
If a field in the user's profile can't be made public over the federation, the
|
||||
responding server MAY choose to exclude it in the response.
|
||||
The profile for the user. If a `field` is specified in the request, only the
|
||||
matching field should be included in the response. If no `field` was specified,
|
||||
the response should include the fields of the user's profile that can be made
|
||||
public, such as the display name and avatar.
|
||||
|
||||
If the user does not have a particular field set on their profile, the server
|
||||
MUST either exclude it from the response body or give it the value `null`.
|
||||
should exclude it from the response body or give it the value `null`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -167,28 +160,20 @@ paths:
|
|||
displayname:
|
||||
type: string
|
||||
description: |-
|
||||
The display name of the user. MUST either be omitted or set to `null` if
|
||||
the user does not have a display name set.
|
||||
The display name of the user. May be omitted if the user does not have a
|
||||
display name set.
|
||||
example: John Doe
|
||||
avatar_url:
|
||||
type: string
|
||||
description: |-
|
||||
The avatar URL for the user's avatar. MUST either be omitted or set to
|
||||
`null` if the user does not have an avatar set.
|
||||
example: mxc://example.org/MyC00lAvatar
|
||||
m.tz:
|
||||
type: string
|
||||
description: The name of the user's time zone. The name SHOULD be registered in
|
||||
the [IANA Time Zone Database](https://www.iana.org/time-zones). Requesting
|
||||
servers MUST tolerate invalid or unknown values.
|
||||
x-addedInMatrixVersion: "1.16"
|
||||
additionalProperties:
|
||||
description: Additional profile fields.
|
||||
The avatar URL for the user's avatar. May be omitted if the user does not
|
||||
have an avatar set.
|
||||
example: mxc://matrix.org/MyC00lAvatar
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"displayname": "John Doe",
|
||||
"avatar_url": "mxc://example.org/MyC00lAvatar"
|
||||
"avatar_url": "mxc://matrix.org/MyC00lAvatar"
|
||||
}
|
||||
"403":
|
||||
x-addedInMatrixVersion: "1.12"
|
||||
|
|
@ -205,7 +190,7 @@ paths:
|
|||
"error": "Profile lookup over federation is disabled on this homeserver"
|
||||
}
|
||||
"404":
|
||||
description: The user does not exist, does not have a profile or the queried field does not exist.
|
||||
description: The user does not exist or does not have a profile.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
|
|||
|
|
@ -1,7 +0,0 @@
|
|||
{
|
||||
"$ref": "core/event.json",
|
||||
"type": "m.key_backup",
|
||||
"content": {
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
|
|
@ -20,13 +20,10 @@ properties:
|
|||
The signatures are calculated using the process described at
|
||||
[Signing JSON](/appendices/#signing-json).
|
||||
type: object
|
||||
patternProperties:
|
||||
"":
|
||||
x-pattern-format: mx-server-name
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
format: mx-unpadded-base64
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
example: {
|
||||
"magic.forest": {
|
||||
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
|
||||
|
|
|
|||
|
|
@ -11,7 +11,5 @@ allOf:
|
|||
The ID of the room associated with this event. Will not be present on events
|
||||
that arrive through `/sync`, despite being required everywhere else.
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
required:
|
||||
- room_id
|
||||
|
|
|
|||
|
|
@ -39,8 +39,6 @@ properties:
|
|||
sender:
|
||||
description: The `sender` for the event.
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
required:
|
||||
- type
|
||||
- state_key
|
||||
|
|
|
|||
|
|
@ -29,13 +29,9 @@ allOf:
|
|||
event_id:
|
||||
description: The globally unique event identifier.
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
sender:
|
||||
description: Contains the fully-qualified ID of the user who sent this event.
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
origin_server_ts:
|
||||
description: Timestamp in milliseconds on originating homeserver
|
||||
when this event was sent.
|
||||
|
|
|
|||
|
|
@ -44,8 +44,7 @@ properties:
|
|||
description: |-
|
||||
The hash (encoded as unpadded base64) of the concatenation of the device's
|
||||
ephemeral public key (encoded as unpadded base64) and the canonical JSON
|
||||
representation of the `content` object of the `m.key.verification.start`
|
||||
message.
|
||||
representation of the `m.key.verification.start` message.
|
||||
m.relates_to:
|
||||
$ref: m.key.verification.m.relates_to.yaml
|
||||
required:
|
||||
|
|
|
|||
|
|
@ -1,24 +0,0 @@
|
|||
---
|
||||
$schema: https://json-schema.org/draft/2020-12/schema
|
||||
|
||||
allOf:
|
||||
- $ref: core-event-schema/event.yaml
|
||||
description: |-
|
||||
Allows clients to track user preferences about key backup.
|
||||
properties:
|
||||
content:
|
||||
type: object
|
||||
properties:
|
||||
enabled:
|
||||
type: boolean
|
||||
description: |-
|
||||
True if the user chose to enable key backup. False if the user chose
|
||||
to disable key backup.
|
||||
required:
|
||||
- enabled
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- m.key_backup
|
||||
title: Key Backup Event
|
||||
type: object
|
||||
|
|
@ -16,8 +16,6 @@ properties:
|
|||
The canonical alias for the room. If not present, null, or empty the
|
||||
room should be considered to have no canonical alias.
|
||||
type: string
|
||||
format: mx-room-alias
|
||||
pattern: "^#"
|
||||
alt_aliases:
|
||||
description: |
|
||||
Alternative aliases the room advertises. This list can have aliases
|
||||
|
|
@ -25,8 +23,6 @@ properties:
|
|||
type: array
|
||||
items:
|
||||
type: string
|
||||
format: mx-room-alias
|
||||
pattern: "^#"
|
||||
type: object
|
||||
state_key:
|
||||
description: A zero-length string.
|
||||
|
|
|
|||
|
|
@ -12,8 +12,6 @@ properties:
|
|||
The `user_id` of the room creator. **Required** for, and only present in, room versions 1 - 10. Starting with
|
||||
room version 11 the event `sender` should be used instead.
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
m.federate:
|
||||
description: Whether users on other servers can join this room. Defaults to `true` if key does not exist.
|
||||
type: boolean
|
||||
|
|
@ -34,13 +32,9 @@ properties:
|
|||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
description: The ID of the old room.
|
||||
event_id:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
deprecated: true
|
||||
x-changedInMatrixVersion:
|
||||
"1.16": |-
|
||||
|
|
@ -57,8 +51,6 @@ properties:
|
|||
type: array
|
||||
items:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
description: Additional user ID to consider a creator of the room, if supported by the room version.
|
||||
x-addedInMatrixVersion: "1.16"
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -55,8 +55,6 @@ properties:
|
|||
enum: ['m.room_membership']
|
||||
room_id:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
description: |-
|
||||
Required if `type` is `m.room_membership`. The room ID to check the
|
||||
user's membership against. If the user is joined to this room, they
|
||||
|
|
|
|||
|
|
@ -76,18 +76,16 @@ properties:
|
|||
join_authorised_via_users_server:
|
||||
x-addedInMatrixVersion: "1.2"
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
description: |-
|
||||
Usually found on `join` events, this field is used to denote which homeserver (through
|
||||
representation of a user with sufficient power level) authorised the user's join. More
|
||||
information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
|
||||
|
||||
Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorisation-rules)
|
||||
Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules)
|
||||
of including this field in further events: in particular, the event must be signed by the
|
||||
server which owns the user ID in the field. When copying the membership event's `content`
|
||||
(for profile updates and similar) it is therefore encouraged to exclude this field in the
|
||||
copy, as otherwise the event might fail event authorisation.
|
||||
copy, as otherwise the event might fail event authorization.
|
||||
reason:
|
||||
x-addedInMatrixVersion: "1.1"
|
||||
type: string
|
||||
|
|
@ -129,8 +127,6 @@ properties:
|
|||
`join`, the user ID sending the event does not need to match the user ID in the `state_key`,
|
||||
unlike other events. Regular authorisation rules still apply.
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
type:
|
||||
enum:
|
||||
- m.room.member
|
||||
|
|
|
|||
|
|
@ -32,8 +32,8 @@ description: |-
|
|||
for `kick` and `ban` default to 50 if they are not specified in the
|
||||
`m.room.power_levels` event, or if the room contains no
|
||||
`m.room.power_levels` event. `invite` defaults to 0 in either case.
|
||||
Other membership values are handled during event authorisation. See
|
||||
the authorisation rules in [room versions](/rooms) for further details.
|
||||
Other membership values are handled during event authorization. See
|
||||
the authorization rules in [room versions](/rooms) for further details.
|
||||
|
||||
For redactions of a user's own events, the required power level is
|
||||
determined by the `m.room.redaction` event power level, as per `events`
|
||||
|
|
|
|||
|
|
@ -10,8 +10,6 @@ properties:
|
|||
redacts:
|
||||
description: The event ID that was redacted. Required for, and present starting in, room version 11.
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
reason:
|
||||
description: 'The reason for the redaction, if any.'
|
||||
type: string
|
||||
|
|
@ -19,8 +17,6 @@ properties:
|
|||
redacts:
|
||||
description: Required for, and only present in, room versions 1 - 10. The event ID that was redacted.
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
type:
|
||||
enum:
|
||||
- m.room.redaction
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@ properties:
|
|||
description: |-
|
||||
Array of redirection URIs for use in redirect-based flows.
|
||||
|
||||
At least one URI is required to use the authorisation code grant.
|
||||
At least one URI is required to use the authorization code grant.
|
||||
|
||||
The server MUST perform [validation on redirect URIs](/client-server-api/#redirect-uri-validation).
|
||||
items:
|
||||
|
|
@ -99,7 +99,7 @@ properties:
|
|||
description: |-
|
||||
Array of the OAuth 2.0 response types that the client may use.
|
||||
|
||||
This MUST include the `code` value to use the authorisation code grant.
|
||||
This MUST include the `code` value to use the authorization code grant.
|
||||
|
||||
The server MUST ignore values that it does not understand.
|
||||
items:
|
||||
|
|
@ -111,7 +111,7 @@ properties:
|
|||
Array of the OAuth 2.0 grant types that the client may use.
|
||||
|
||||
This MUST include:
|
||||
- the `authorization_code` value to use the authorisation code grant,
|
||||
- the `authorization_code` value to use the authorization code grant,
|
||||
- the `refresh_token` value to use the refresh token grant.
|
||||
|
||||
The server MUST ignore values that it does not understand.
|
||||
|
|
|
|||
|
|
@ -66,11 +66,6 @@ mx-mxc-uri:
|
|||
url: client-server-api#matrix-content-mxc-uris
|
||||
# regex: "^mxc:\\/\\/"
|
||||
|
||||
mx-unpadded-base64:
|
||||
title: Unpadded Base64
|
||||
url: appendices#unpadded-base64
|
||||
# no regex
|
||||
|
||||
uri:
|
||||
title: URI
|
||||
url: https://datatracker.ietf.org/doc/html/rfc3986
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue