Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-21 21:43:43 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Merge branch 'main' into oauth2-token-revocation

Browse source
This commit is contained in:
Richard van der Hoff 2025-06-20 10:48:12 +01:00 committed by GitHub
parent 6309cff957 e4740e36e8
commit 55b1ac0606
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 1095 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2125.feature Normal file
View file

@ -0,0 +1 @@
Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

1
changelogs/client_server/newsfragments/2147.new Normal file
View file

@ -0,0 +1 @@
Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965).

1
changelogs/client_server/newsfragments/2148.feature Normal file
View file

@ -0,0 +1 @@
Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

1
changelogs/client_server/newsfragments/2149.feature Normal file
View file

@ -0,0 +1 @@
Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

1
changelogs/client_server/newsfragments/2150.feature Normal file
View file

@ -0,0 +1 @@
Add the OAuth 2.0 based authentication API, as per [MSC3861](https://github.com/matrix-org/matrix-spec-proposals/pull/3861) and its sub-proposals.

1
changelogs/client_server/newsfragments/2154.clarification Normal file
View file

@ -0,0 +1 @@
Add missing fields in example for `ExportedSessionData`.

1
changelogs/client_server/newsfragments/2158.feature Normal file
View file

@ -0,0 +1 @@
Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

1
changelogs/server_server/newsfragments/2125.feature Normal file
View file

@ -0,0 +1 @@
Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266).

547
content/client-server-api/_index.md
View file

@ -1481,6 +1481,549 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
### OAuth 2.0 API
#### Login flow
Logging in with the OAuth 2.0 API should be done with the [authorization code
grant](#authorization-code-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.
Once the client has retrieved the [server metadata](#server-metadata-discovery),
it 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 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 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.
**Authorization request**
The client then constructs the authorization request URL using the
`authorization_endpoint` value, with the following query parameters:
| Parameter | Value |
|-------------------------|----------------------------------------------------|
| `response_type` | `code` |
| `client_id` | The client ID returned from client registration. |
| `redirect_uri` | The redirect URI that MUST match one of the values registered in the client metadata |
| `scope` | `urn:matrix:client:api:* urn:matrix:client:device:<device_id>` with the `device_id` generated previously. |
| `state` | The `state` value generated previously. |
| `response_mode` | `fragment` or `query` (see "[Callback](#callback)" below). |
| `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 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.
- For native clients, this can be done by opening the URL using the system
browser, or, when available, through platform-specific APIs such as
[`ASWebAuthenticationSession`](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession)
on iOS or [Android Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs).
Sample authorization request, with extra whitespaces for readability:
```
https://account.example.com/oauth2/auth?
client_id = s6BhdRkqt3 &
response_type = code &
response_mode = fragment &
redirect_uri = https://app.example.com/oauth2-callback &
scope = urn:matrix:client:api:* urn:matrix:client:device:AAABBBCCCDDD &
state = ewubooN9weezeewah9fol4oothohroh3 &
code_challenge = 72xySjpngTcCxgbPfFmkPHjMvVDl2jW1aWP7-J6rmwU &
code_challenge_method = S256
```
<a id="callback"></a> **Callback**
Once completed, the user is redirected to the `redirect_uri`, with either a
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:
- If set to `fragment`, the parameters will be placed in the URL fragment, like
`https://example.com/callback#param1=value1&param2=value2`.
- If set to `query`, the parameters will be in placed the query string, like
`com.example.app:/callback?param1=value1&param2=value2`.
To avoid disclosing the parameters to the web server hosting the `redirect_uri`,
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 authorization request.
A successful authorization will have a `code` value, for example:
```
https://app.example.com/oauth2-callback#state=ewubooN9weezeewah9fol4oothohroh3&code=iuB7Eiz9heengah1joh2ioy9ahChuP6R
```
A failed authorization will have the following values:
- `error`: the error code
- `error_description`: the error description (optional)
- `error_uri`: the URI where the user can find more information about the error (optional)
For example:
```
https://app.example.com/oauth2-callback#state=ewubooN9weezeewah9fol4oothohroh3&error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&error_uri=https%3A%2F%2Ferrors.example.com%2F
```
**Token request**
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
parameters, encoded as `application/x-www-form-urlencoded` in the body:
| Parameter | Value |
|-----------------|------------------------------------------------------------|
| `grant_type` | `authorization_code` |
| `code` | The value of `code` obtained from the callback. |
| `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 authorization flow. |
The server replies with a JSON object containing the access token, the token
type, the expiration time, and the refresh token.
Sample token request:
```
POST /oauth2/token HTTP/1.1
Host: account.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
grant_type=authorization_code
&code=iuB7Eiz9heengah1joh2ioy9ahChuP6R
&redirect_uri=https://app.example.com/oauth2-callback
&client_id=s6BhdRkqt3
&code_verifier=ogie4iVaeteeKeeLaid0aizuimairaCh
```
Sample response:
```json
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in": 299,
"refresh_token": "tGz3JOkF0XG5Qx2TlKWIA",
"scope": "urn:matrix:client:api:* urn:matrix:client:device:AAABBBCCCDDD"
}
```
Finally, the client can call the [`/whoami`](#get_matrixclientv3accountwhoami)
endpoint to get the user ID that owns the access token.
#### Token refresh flow
Refreshing a token with the OAuth 2.0 API should be done with the [refresh token
grant](#refresh-token-grant).
When the access token expires, the client must refresh it by making a `POST`
request to the `token_endpoint` with the following parameters, encoded as
`application/x-www-form-urlencoded` in the body:
| Parameter | Value |
|-----------------|------------------------------------------------------------|
| `grant_type` | `refresh_token` |
| `refresh_token` | The `refresh_token` obtained from the token response during the last token request. |
| `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 authorization
flow.
#### Server metadata discovery
{{% http-api spec="client-server" api="oauth_server_metadata" %}}
#### Client registration
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
[RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591).
##### Client metadata
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.
{{% definition path="schemas/oauth2-client-metadata" %}}
###### Metadata localization
As per [RFC 7591 section 2.2](https://tools.ietf.org/html/rfc7591#section-2.2),
all the human-readable metadata values MAY be localized.
The human-readable values include:
- `client_name`
- `logo_uri`
- `tos_uri`
- `policy-uri`
For example:
```json
{
"client_name": "Digital mailbox",
"client_name#en-US": "Digital mailbox",
"client_name#en-GB": "Digital postbox",
"client_name#fr": "Boîte aux lettres numérique",
"tos_uri": "https://example.com/tos.html",
"tos_uri#fr": "https://example.com/fr/tos.html",
"policy_uri": "https://example.com/policy.html",
"policy_uri#fr": "https://example.com/fr/policy.html"
}
```
###### Redirect URI validation
The redirect URI plays a critical role in validating the authenticity of the
client. The client "proves" its identity by demonstrating that it controls the
redirect URI. This is why it is critical to have strict validation of the
redirect URI.
The `application_type` metadata is used to determine the type of client.
In all cases, the redirect URI MUST NOT have a fragment component.
**Web clients**
`web` clients can use redirect URIs that:
- MUST use the `https` scheme.
- MUST NOT use a user or password in the authority component of the URI.
- MUST use the client URI as a common base for the authority component, as
defined previously.
- MAY include an `application/x-www-form-urlencoded` formatted query component.
For example, with `https://example.com/` as the client URI, the following are
valid redirect URIs:
- `https://example.com/callback`
- `https://app.example.com/callback`
- `https://example.com:5173/?query=value`
With the same client URI, the following are invalid redirect URIs:
- `https://example.com/callback#fragment`
- `http://example.com/callback`
- `http://localhost/`
**Native clients**
`native` clients can use three types of redirect URIs:
1. **Private-Use URI Scheme**
- The scheme MUST be prefixed with the client URI hostname in reverse-DNS
notation. For example, if the client URI is `https://example.com/`, then a
valid custom URI scheme would be `com.example.app:/`.
- There MUST NOT be an authority component. This means that the URI MUST have
either a single slash or none immediately following the scheme, with no
hostname, username, or port.
2. **`http` URI on the loopback interface**
- 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 authorization flow.
3. **Claimed `https` Scheme URI**
Some operating systems allow apps to claim `https` scheme URIs in the
domains they control. When the browser encounters a claimed URI, instead of
the page being loaded in the browser, the native app is launched with the
URI supplied as a launch parameter. The same rules as for `web` clients
apply.
These restrictions are the same as defined by [RFC 8252 section 7](https://tools.ietf.org/html/rfc8252#section-7).
For example, with `https://example.com/` as the client URI,
These are valid redirect URIs:
- `com.example.app:/callback`
- `com.example:/`
- `com.example:callback`
- `http://localhost/callback`
- `http://127.0.0.1/callback`
- `http://[::1]/callback`
These are invalid redirect URIs:
- `example:/callback`
- `com.example.app://callback`
- `https://localhost/callback`
- `http://localhost:1234/callback`
##### Dynamic client registration flow
To register, the client sends an HTTP `POST` request to the
`registration_endpoint`, which can be found in the [server metadata](#server-metadata-discovery).
The body of the request is the JSON-encoded [`OAuthClientMetadata`](#client-metadata).
For example, the client could send the following registration request:
```http
POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Server: auth.example.com
```
```json
{
"client_name": "My App",
"client_name#fr": "Mon application",
"client_uri": "https://example.com/",
"logo_uri": "https://example.com/logo.png",
"tos_uri": "https://example.com/tos.html",
"tos_uri#fr": "https://example.com/fr/tos.html",
"policy_uri": "https://example.com/policy.html",
"policy_uri#fr": "https://example.com/fr/policy.html",
"redirect_uris": ["https://app.example.com/callback"],
"token_endpoint_auth_method": "none",
"response_types": ["code"],
"grant_types": [
"authorization_code",
"refresh_token",
"urn:ietf:params:oauth:grant-type:token-exchange"
],
"application_type": "web"
}
```
Upon successful registration, the server replies with an `HTTP 201 Created`
response, with a JSON object containing the allocated `client_id` and all the
registered metadata values.
With the registration request above, the server might reply with:
```json
{
"client_id": "s6BhdRkqt3",
"client_name": "My App",
"client_uri": "https://example.com/",
"logo_uri": "https://example.com/logo.png",
"tos_uri": "https://example.com/tos.html",
"policy_uri": "https://example.com/policy.html",
"redirect_uris": ["https://app.example.com/callback"],
"token_endpoint_auth_method": "none",
"response_types": ["code"],
"grant_types": ["authorization_code", "refresh_token"],
"application_type": "web"
}
```
In this example, the server has not registered the locale-specific values for
`client_name`, `tos_uri`, and `policy_uri`, which is why they are not present in
the response. The server also does not support the
`urn:ietf:params:oauth:grant-type:token-exchange` grant type, which is why it is
not present in the response.
The client MUST store the `client_id` for future use.
To avoid the number of client registrations growing over time, the server MAY
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
authorization flow.
{{% boxes/note %}}
Because each client on each user device will do its own registration, they may
all have different `client_id`s. This means that the server may store the same
client registration multiple times, which could lead to a large number of client
registrations.
This can be mitigated by de-duplicating client registrations that have identical
metadata. By doing so, different users on different devices using the same
client can share a single `client_id`, reducing the overall number of
registrations.
{{% /boxes/note %}}
#### Scope
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.
A scope is defined in [RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)
as a string containing a list of space-separated scope tokens.
{{% boxes/note %}}
The framework encourages the practice of obtaining additional user consent when
a client asks for a new scope that was not granted previously. This could be
used by future MSCs to replace the legacy [User-Interactive Authentication API](#user-interactive-authentication-api).
{{% /boxes/note %}}
##### Scope token format
All scope tokens related to Matrix should start with `urn:matrix:` and use the
`:` delimiter for further sub-division.
Scope tokens related to mapping of Client-Server API access levels should start
with `urn:matrix:client:`.
{{% boxes/note %}}
For MSCs that build on this namespace, unstable subdivisions should be used
whilst in development. For example, if MSCXXXX wants to introduce the
`urn:matrix:client:foo` scope, it could use
`urn:matrix:client:com.example.mscXXXX.foo` during development.
If it needs to introduce multiple scopes, like `urn:matrix:client:foo` and
`urn:matrix:client:bar`, it could use
`urn:matrix:client:com.example.mscXXXX:foo` and
`urn:matrix:client:com.example.mscXXXX:bar`.
{{% /boxes/note %}}
##### Allocated scope tokens
This specification defines the following scope tokens:
- [`urn:matrix:client:api:*`](#full-client-server-api-readwrite-access)
- [`urn:matrix:client:device:<device_id>`](#device-id-allocation)
###### Full client-server API read/write access
| Scope | Purpose |
|---------------------------|---------------------------------------------|
| `urn:matrix:client:api:*` | Grants full access to the Client-Server API. |
{{% boxes/note %}}
This token matches the behavior of the legacy authentication API. Future MSCs
could introduce more fine-grained scope tokens like
`urn:matrix:client:api:read:*` for read-only access.
{{% /boxes/note %}}
###### Device ID allocation
| Scope | Purpose |
|----------------------------------------|----------------------------------------------------------------------------------------------|
| `urn:matrix:client:device:<device_id>` | Allocates the given `device_id` and associates it to the generated access and refresh tokens. |
Contrary to the legacy login and registration APIs where the homeserver is
typically the one generating a `device_id` and providing it to the client, with
the OAuth 2.0 API, the client is responsible for allocating the `device_id`.
There MUST be exactly one `urn:matrix:client:device:<device_id>` token in the
requested scope in the login flow.
When generating a new `device_id`, the client SHOULD generate a random string
with enough entropy. It SHOULD only use characters from the unreserved character
list defined by [RFC 3986 section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3):
```
unreserved = a-z / A-Z / 0-9 / "-" / "." / "_" / "~"
```
Using this alphabet, a 10 character string is enough to stand a sufficient
chance of being unique per user. The homeserver MAY reject a request for a
`device_id` that is not long enough or contains characters outside the
unreserved list.
In any case it MUST only use characters allowed by the OAuth 2.0 scope
definition in [RFC 6749 section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3),
which is defined as the following ASCII ranges:
```
%x21 / %x23-5B / %x5D-7E
```
This definition matches:
- alphanumeric characters: `A-Z`, `a-z`, `0-9`
- the following characters: ``! # $ % & ' ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~``
#### Grant types
[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 [authorization
server metadata](#server-metadata-discovery):
- `token_endpoint`
- `grant_types_supported`
The client must also have obtained a `client_id` by [registering with the server](#client-registration).
This specification supports the following grant types:
- [Authorization code grant](#authorization-code-grant)
- [Refresh token grant](#refresh-token-grant)
##### Authorization code grant
As per [RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1),
the authorization code grant lets the client obtain an access token through a
browser redirect.
This grant requires the client to know the following [authorization server
metadata](#server-metadata-discovery):
- `authorization_endpoint`
- `response_types_supported`
- `response_mode_supported`
To use this grant, homeservers and clients MUST:
- 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.
- Use the `fragment` response mode as per [OAuth 2.0 Multiple Response Type
Encoding Practices](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html)
for clients with an HTTPS redirect URI.
###### User registration
Clients can signal to the server that the user desires to register a new account
by initiating the 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` authorization server metadata.
Servers that support this parameter SHOULD show the account registration UI in
the browser.
##### Refresh token grant
As per [RFC 6749 section 6](https://datatracker.ietf.org/doc/html/rfc6749#section-6),
the refresh token grant lets the client exchange a refresh token for an access
token.
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
`refresh_token` when expired.
The homeserver SHOULD issue a new refresh token each time an old one is used,
and invalidate the old one. However, it MUST ensure that the client is able to
retry the refresh request in the case that the response to the request is lost.
The homeserver SHOULD consider that the session is compromised if an old,
invalidated refresh token is used, and SHOULD revoke the session.
The client MUST handle access token refresh failures as follows:
- If the refresh fails due to network issues or a `5xx` HTTP status code from
the server, the client should retry the request with the old refresh token
later.
- If the refresh fails due to a `4xx` HTTP status code from the server, the
client should consider the session logged out.
#### Token revocation
When a user wants to log out from a client, the client SHOULD use OAuth 2.0
@ -2970,6 +3513,10 @@ that are not `world_readable` regardless of their visibility.
{{% http-api spec="client-server" api="list_public_rooms" %}}
### Room Summaries
{{% http-api spec="client-server" api="room_summary" %}}
## User Data
### User Directory

16
data/api/client-server/definitions/key_backup_session_data.yaml
View file

@ -23,6 +23,7 @@ properties:
type: string
description: |-
The end-to-end message encryption algorithm that the key is for. Must be `m.megolm.v1.aes-sha2`.
example: "m.megolm.v1.aes-sha2"
forwarding_curve25519_key_chain:
type: array
items:
@ -30,31 +31,24 @@ properties:
description: |-
Chain of Curve25519 keys through which this session was forwarded, via [m.forwarded_room_key](/client-server-api/#mforwarded_room_key)
events.
example: [ "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" ]
sender_key:
type: string
description: |-
Unpadded base64-encoded device Curve25519 key.
example: "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU"
sender_claimed_keys:
type: object
additionalProperties:
type: string
description: |-
A map from algorithm name (`ed25519`) to the Ed25519 signing key of the sending device.
example: { "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y" }
session_key:
type: string
description: |-
Unpadded base64-encoded session key in [session-export format](https://gitlab.matrix.org/matrix-org/olm/blob/master/docs/megolm.md#session-export-format).
example: {
"algorithm": "m.megolm.v1.aes-sha2",
"forwarding_curve25519_key_chain": [
"hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
],
"sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
"sender_claimed_keys": {
"ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
},
"session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
}
example: "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
required:
- algorithm
- forwarding_curve25519_key_chain

5
data/api/client-server/definitions/public_rooms_chunk.yaml
View file

@ -17,6 +17,8 @@ title: "PublishedRoomsChunk"
properties:
canonical_alias:
type: string
format: mx-room-alias
pattern: "^#"
description: The canonical alias of the room, if any.
example: "#general:example.org"
name:
@ -29,6 +31,8 @@ properties:
example: 42
room_id:
type: string
format: mx-room-id
pattern: "^!"
description: The ID of the room.
example: "!abcdefg:example.org"
topic:
@ -61,7 +65,6 @@ properties:
example: "public"
room_type:
type: string
x-addedInMatrixVersion: "1.4"
description: |-
The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any.
required:

50
data/api/client-server/definitions/room_summary.yaml Normal file
View file

@ -0,0 +1,50 @@
# Copyright 2025 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: RoomSummary
allOf:
- $ref: public_rooms_chunk.yaml
- type: object
properties:
room_type:
type: string
description: The `type` of room (from
[`m.room.create`](/client-server-api/#mroomcreate)),
if any.
allowed_room_ids:
type: array
items:
type: string
format: mx-room-id
pattern: "^!"
description: |-
If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
are specified by the join rules. Empty or omitted otherwise.
encryption:
type: string
enum:
- "m.megolm.v1.aes-sha2"
description: |-
The encryption algorithm to be used to encrypt messages sent in the
room.
room_version:
description: The version of the room.
type: string
required:
- room_id
- num_joined_members
- world_readable
- guest_can_join

176
data/api/client-server/oauth_server_metadata.yaml Normal file
View file

@ -0,0 +1,176 @@
# Copyright 2025 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
openapi: 3.1.0
info:
title: Matrix Client-Server OAuth 2.0 Server Metadata Discovery API
version: 1.0.0
paths:
"/auth_metadata":
get:
summary: Get the OAuth 2.0 authorization server metadata.
description: |-
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 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 authorization server metadata is relatively large and may change
over time. Clients should:
- Cache the metadata appropriately based on HTTP caching headers
- Refetch the metadata if it is stale
{{% /boxes/note %}}
operationId: getAuthMetadata
responses:
"200":
description: The OAuth 2.0 authorization server metadata.
content:
application/json:
schema:
type: object
properties:
issuer:
type: string
format: uri
description: |-
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
by [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).
authorization_endpoint:
type: string
format: uri
description: |-
URL of the authorization endpoint, necessary to use the authorization code
grant.
token_endpoint:
type: string
format: uri
description: |-
URL of the token endpoint, necessary to use the authorization code grant and
the refresh token grant.
revocation_endpoint:
type: string
format: uri
description: |-
URL of the revocation endpoint, necessary to log out a client by invalidating
its access and refresh tokens.
registration_endpoint:
type: string
format: uri
description: |-
URL of the client registration endpoint, necessary to perform dynamic
registration of a client.
response_types_supported:
type: array
description: |-
List of OAuth 2.0 response type strings that the server supports at the
authorization endpoint.
This array MUST contain at least the `code` value, for clients to be able to
use the authorization code grant.
items:
type: string
description: A response type that the server supports.
grant_types_supported:
type: array
description: |-
List of OAuth 2.0 grant type strings that the server supports at the token
endpoint.
This array MUST contain at least the `authorization_code` and `refresh_token`
values, for clients to be able to use the authorization code grant and refresh
token grant, respectively.
items:
type: string
description: A grant type that the server supports.
response_modes_supported:
type: array
description: |-
List of OAuth 2.0 response mode strings that the server supports at the
authorization endpoint.
This array MUST contain at least the `query` and `fragment` values, for
improved security in the authorization code grant.
items:
type: string
description: A response mode that the server supports.
code_challenge_methods_supported:
type: array
description: |-
List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods
that the server supports at the authorization endpoint.
This array MUST contain at least the `S256` value, for improved security in
the authorization code grant.
items:
type: string
description: A PKCE code challenge method that the server supports.
prompt_values_supported:
type: array
description: |-
List of OpenID Connect prompt values that the server supports at the
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
supported, for a client to signal to the server that the user desires to
register a new account.
items:
type: string
description: A prompt value that the server supports.
required:
- issuer
- authorization_endpoint
- token_endpoint
- revocation_endpoint
- registration_endpoint
- response_types_supported
- grant_types_supported
- response_modes_supported
- code_challenge_methods_supported
example: {
"issuer": "https://account.example.com/",
"authorization_endpoint": "https://account.example.com/oauth2/auth",
"token_endpoint": "https://account.example.com/oauth2/token",
"registration_endpoint": "https://account.example.com/oauth2/clients/register",
"revocation_endpoint": "https://account.example.com/oauth2/revoke",
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"response_modes_supported": ["query", "fragment"],
"code_challenge_methods_supported": ["S256"],
}
tags:
- Session management
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1

143
data/api/client-server/room_summary.yaml Normal file
View file

@ -0,0 +1,143 @@
# Copyright 2025 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
openapi: 3.1.0
info:
title: Matrix Client-Server Room Summary API
version: 1.0.0
paths:
"/room_summary/{roomIdOrAlias}":
get:
x-addedInMatrixVersion: "1.15"
summary: Retrieves a summary for a room.
description: |-
Retrieves a summary for a room.
Clients should note that requests for rooms where the user's membership
is `invite` or `knock` might yield outdated, partial or even no data
since the server may not have access to the current state of the room.
Servers MAY allow unauthenticated access to this API if at least one of
the following conditions holds true:
- The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or
`knock_restricted`.
- The room has a `world_readable` [history visibility](#room-history-visibility).
Servers should consider rate limiting requests that require a federation
request more heavily if the client is unauthenticated.
operationId: getRoomSummary
security:
- signedRequest: []
parameters:
- in: path
name: roomIdOrAlias
description: The room identifier or alias to summarise.
required: true
example: "#monkeys:matrix.org"
schema:
oneOf:
- type: string
format: mx-room-id
pattern: "^!"
- type: string
format: mx-room-alias
pattern: "^#"
- in: query
name: via
description: |-
The servers to attempt to request the summary from when
the local server cannot generate it (for instance, because
it has no local user in the room).
example:
- matrix.org
- elsewhere.ca
schema:
type: array
items:
type: string
format: mx-server-name
responses:
"200":
description: A summary of the room.
content:
application/json:
schema:
description: A summary of the room.
allOf:
- $ref: ../client-server/definitions/room_summary.yaml
- type: object
properties:
membership:
description: |-
The membership state of the user if the user is joined to the room. Absent
if the API was called unauthenticated.
enum:
- invite
- join
- knock
- leave
- ban
type: string
required:
- guest_can_join
- num_joined_members
- room_id
- world_readable
examples:
response:
value: {
room_id: "!ol19s:bleecker.street",
avatar_url: "mxc://bleecker.street/CHEDDARandBRIE",
guest_can_join: false,
name: "CHEESE",
num_joined_members: 37,
topic: "Tasty tasty cheese",
world_readable: true,
join_rule: "public",
room_type: "m.space",
membership: "invite",
encryption: "m.megolm.v1.aes-sha2",
room_version: "9001",
}
"404":
description: |-
The room could not be found.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Room not found."
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
accessTokenQuery:
$ref: definitions/security.yaml#/accessTokenQuery
accessTokenBearer:
$ref: definitions/security.yaml#/accessTokenBearer

15
data/api/client-server/space_hierarchy.yaml
View file

@ -102,15 +102,10 @@ paths:
* The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`.
items:
allOf:
- $ref: definitions/public_rooms_chunk.yaml
- $ref: definitions/room_summary.yaml
- type: object
title: SpaceHierarchyRoomsChunk
properties:
room_type:
type: string
description: The `type` of room (from
[`m.room.create`](/client-server-api/#mroomcreate)),
if any.
children_state:
type: array
description: |-
@ -130,6 +125,14 @@ paths:
description: The `origin_server_ts` for the event.
required:
- origin_server_ts
room_type:
x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
allowed_room_ids:
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
encryption:
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
room_version:
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
required:
- children_state
next_batch:

38
data/api/server-server/space_hierarchy.yaml
View file

@ -61,22 +61,10 @@ paths:
room:
description: A summary of the room requested.
allOf:
- $ref: ../client-server/definitions/public_rooms_chunk.yaml
- $ref: ../client-server/definitions/room_summary.yaml
- type: object
title: SpaceHierarchyParentRoom
properties:
room_type:
type: string
description: The `type` of room (from
[`m.room.create`](/client-server-api/#mroomcreate)),
if any.
allowed_room_ids:
type: array
items:
type: string
description: |-
If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
are specified by the join rules. Empty or omitted otherwise.
children_state:
type: array
description: |-
@ -96,6 +84,12 @@ paths:
description: The `origin_server_ts` for the event.
required:
- origin_server_ts
room_type:
x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
encryption:
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
room_version:
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
required:
- children_state
children:
@ -105,22 +99,16 @@ paths:
be excluded.
items:
allOf:
- $ref: ../client-server/definitions/public_rooms_chunk.yaml
- $ref: ../client-server/definitions/room_summary.yaml
- type: object
title: SpaceHierarchyChildRoomsChunk
properties:
room_type:
type: string
description: The `type` of room (from
[`m.room.create`](/client-server-api/#mroomcreate)),
if any.
allowed_room_ids:
type: array
items:
type: string
description: |-
If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which
are specified by the join rules. Empty or omitted otherwise.
x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
encryption:
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
room_version:
x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
inaccessible_children:
type: array
items:

140
data/schemas/oauth2-client-metadata.yaml Normal file
View file

@ -0,0 +1,140 @@
# Copyright 2025 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
title: OAuthClientMetadata
type: object
description: |-
This definition of the metadata specifies only the fields that are meaningful
in the context of the Matrix specification. All the possible values are
registered in the [OAuth Dynamic Client Registration Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#client-metadata),
and normative definitions of them are available in their respective RFCs.
properties:
client_uri:
type: string
format: uri
description: |-
A URL to a valid web page that SHOULD give the user more information about
the client.
This URL MUST use the `https` scheme and SHOULD NOT require authentication
to access. It MUST NOT use a user or password in the authority component
of the URI.
The server MAY reject client registrations if this field is invalid or
missing.
This URI is a common base for all the other URIs in the metadata: those
MUST be either on the same host or on a subdomain of the host of the
`client_uri`. The port number, path and query components MAY be different.
For example, if the `client_uri` is `https://example.com/`, then one of
the `redirect_uris` can be `https://example.com/callback` or
`https://app.example.com/callback`, but not `https://app.com/callback`.
client_name:
type: string
description: |-
Human-readable name of the client to be presented to the user.
This field can be [localized](/client-server-api/#metadata-localization).
logo_uri:
type: string
format: uri
description: |-
URL that references a logo for the client.
This URL MUST use the `https` scheme.
This field can be [localized](/client-server-api/#metadata-localization).
tos_uri:
type: string
format: uri
description: |-
URL that points to a human-readable terms of service document for the
client.
This URL MUST use the `https` scheme and SHOULD NOT require authentication
to access. It MUST NOT use a user or password in the authority component
of the URI.
If this field is set, the server SHOULD show or link to this URL.
This field can be [localized](/client-server-api/#metadata-localization).
policy_uri:
type: string
format: uri
description: |-
URL that points to a human-readable policy document for the client.
This URL MUST use the `https` scheme and SHOULD NOT require authentication
to access. It MUST NOT use a user or password in the authority component
of the URI.
If this field is set, the server SHOULD show or link to this URL.
This field can be [localized](/client-server-api/#metadata-localization).
redirect_uris:
type: array
description: |-
Array of redirection URIs for use in redirect-based flows.
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:
type: string
format: uri
description: A redirection URI.
response_types:
type: array
description: |-
Array of the OAuth 2.0 response types that the client may use.
This MUST include the `code` value to use the authorization code grant.
The server MUST ignore values that it does not understand.
items:
type: string
description: A response type that the client may use.
grant_types:
type: array
description: |-
Array of the OAuth 2.0 grant types that the client may use.
This MUST include:
- 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.
items:
type: string
description: A grant type that the client may use.
token_endpoint_auth_method:
type: string
description: |-
String indicator of the requested authentication method for the token
endpoint.
The homeserver MUST support the `none` value, as most Matrix clients are
client-side only, do not have a server component, and therefore are public
clients.
application_type:
type: string
description: |-
Kind of the application.
The homeserver MUST support the `web` and `native` values to be able to
perform [redirect URI validation](/client-server-api/#redirect-uri-validation).
Defaults to `web` if omitted.
required:
- client_uri