Merge 6646146f8c into 6edb6ba1cd

* Clarify that SSO login applies to the legacy authentication API

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Do not point to specific authentication API for obtaining access token

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add warnings about incompatibility with OAuth 2.0 to endpoints that use UIA

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add note about API standards not applying to OAuth 2.0

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Apply suggestions from code review

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Travis Ralston <travpc@gmail.com>

changelogs/application_service/newsfragments/2130.feature

@@ -1 +0,0 @@
-Correct null value handling for the AS Registration's `url` property.

changelogs/client_server/newsfragments/2068.clarification

@@ -1 +0,0 @@
-Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty.

changelogs/client_server/newsfragments/2071.feature

@@ -0,0 +1 @@
+Feature: Update profile endpoints to become generic to support [MSC4133](https://github.com/matrix-org/matrix-spec-proposals/pull/4133) extended fields. Extended profile fields are now supported via the new `m.profile_fields` capability, which deprecates the previous `m.set_avatar_url` and `m.set_displayname` capabilities. Stabilised keys are explicitly enumerated, and custom keys must conform to the Common Namespaced Identifier Grammar.

changelogs/client_server/newsfragments/2077.clarification

@@ -1 +0,0 @@
-Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places.

changelogs/client_server/newsfragments/2083.clarification

@@ -1,2 +0,0 @@
-Clarify the format of third-party invites, including the fact that identity
-server public keys can be encoded using standard or URL-safe base64.

changelogs/client_server/newsfragments/2095.feature

@@ -1 +0,0 @@
-Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765).

changelogs/client_server/newsfragments/2101.clarification

@@ -1 +0,0 @@
-"Public" rooms in profile look-ups are defined through their join rule and history visibility.

changelogs/client_server/newsfragments/2102.clarification

@@ -1 +0,0 @@
-"Public" rooms in user directory queries are defined through their join rule and history visibility.

changelogs/client_server/newsfragments/2104.clarification

@@ -1 +0,0 @@
-Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

changelogs/client_server/newsfragments/2106.clarification

@@ -1 +0,0 @@
-"Public" rooms with respect to call invites are defined through their join rule.

changelogs/client_server/newsfragments/2107.clarification

@@ -1 +0,0 @@
-"Public" rooms have no specific meaning with respect to moderation policy lists.

changelogs/client_server/newsfragments/2108.clarification

@@ -1 +0,0 @@
-"Public" rooms with respect to presence are defined through their join rule.

changelogs/client_server/newsfragments/2109.clarification

@@ -1 +0,0 @@
-Spaces are subject to the same access mechanisms as rooms.

changelogs/client_server/newsfragments/2121.clarification

@@ -1 +0,0 @@
-Fix various typos throughout the specification.

changelogs/client_server/newsfragments/2122.feature

@@ -1 +0,0 @@
-Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147).

changelogs/client_server/newsfragments/2125.feature

@@ -1 +0,0 @@
-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).

changelogs/client_server/newsfragments/2140.clarification

@@ -1 +0,0 @@
-Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

changelogs/client_server/newsfragments/2141.feature

@@ -1 +0,0 @@
-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.

changelogs/client_server/newsfragments/2144.clarification

@@ -1 +0,0 @@
-Fix typo: as->has.

changelogs/client_server/newsfragments/2147.new

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

changelogs/client_server/newsfragments/2148.feature

@@ -1 +0,0 @@
-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.

changelogs/client_server/newsfragments/2149.feature

@@ -1 +0,0 @@
-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.

changelogs/client_server/newsfragments/2150.feature

@@ -1 +0,0 @@
-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.

changelogs/client_server/newsfragments/2151.feature

@@ -1 +0,0 @@
-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.

changelogs/client_server/newsfragments/2154.clarification

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

changelogs/client_server/newsfragments/2158.feature

@@ -1 +0,0 @@
-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).

changelogs/client_server/newsfragments/2159.feature

@@ -1 +0,0 @@
-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.

changelogs/identity_service/newsfragments/2083.clarification

@@ -1 +0,0 @@
-Clarify that public keys can be encoded using standard or URL-safe base64.

changelogs/internal/newsfragments/2081.clarification

@@ -1 +0,0 @@
-Adjust margins in rendered endpoints.

changelogs/internal/newsfragments/2088.clarification

@@ -1 +0,0 @@
-Replace Hugo shortcodes in OpenAPI output.

changelogs/internal/newsfragments/2115.clarification

@@ -1 +0,0 @@
-Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks.

changelogs/internal/newsfragments/2123.clarification

@@ -1 +0,0 @@
-Fix the historical info box when generating the historical spec in CI.

changelogs/internal/newsfragments/2137.clarification

@@ -1 +0,0 @@
-Update the header navigation menu with links to modern matrix.org. Contributed by @HarHarLinks.

changelogs/server_server/newsfragments/2067.clarification

@@ -1 +0,0 @@
-Add a note to the invite endpoints that invites to local users may be received twice over federation if the homeserver is already in the room.

changelogs/server_server/newsfragments/2083.clarification

@@ -1,2 +0,0 @@
-Clarify the format of third-party invites, including the fact that identity
-server public keys can be encoded using standard or URL-safe base64.

changelogs/server_server/newsfragments/2095.feature

@@ -1 +0,0 @@
-Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765).

changelogs/server_server/newsfragments/2100.clarification

@@ -1 +0,0 @@
-Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`.

changelogs/server_server/newsfragments/2104.clarification

@@ -1 +0,0 @@
-Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

changelogs/server_server/newsfragments/2125.feature

@@ -1 +0,0 @@
-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).

changelogs/server_server/newsfragments/2128.clarification

@@ -1 +0,0 @@
-Fix various typos throughout the specification.

changelogs/server_server/newsfragments/2140.clarification

@@ -1 +0,0 @@
-Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

config/_default/hugo.toml

@@ -67,7 +67,7 @@ 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 = "14"
+# minor = "15"
 
 # User interface configuration
 [params.ui]

content/changelog/v1.15.md

@@ -0,0 +1,97 @@
+---
+title: v1.15 Changelog
+linkTitle: v1.15
+type: docs
+layout: changelog
+outputs:
+  - html
+  - checklist
+date: 2025-06-26
+---
+
+## Client-Server API
+
+**New Endpoints**
+
+- Add `GET /_matrix/client/v1/room_summary/{roomIdOrAlias}`, as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125))
+- Add `GET /_matrix/client/v1/auth_metadata`, as per [MSC2965](https://github.com/matrix-org/matrix-spec-proposals/pull/2965). ([#2147](https://github.com/matrix-org/matrix-spec/issues/2147))
+
+**Backwards Compatible Changes**
+
+- Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765). ([#2095](https://github.com/matrix-org/matrix-spec/issues/2095))
+- Include device keys with Olm-encrypted events as per [MSC4147](https://github.com/matrix-org/matrix-spec-proposals/pull/4147). ([#2122](https://github.com/matrix-org/matrix-spec/issues/2122))
+- 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). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125), [#2158](https://github.com/matrix-org/matrix-spec/issues/2158))
+- 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. ([#2141](https://github.com/matrix-org/matrix-spec/issues/2141), [#2148](https://github.com/matrix-org/matrix-spec/issues/2148), [#2149](https://github.com/matrix-org/matrix-spec/issues/2149), [#2150](https://github.com/matrix-org/matrix-spec/issues/2150), [#2151](https://github.com/matrix-org/matrix-spec/issues/2151), [#2159](https://github.com/matrix-org/matrix-spec/issues/2159), [#2164](https://github.com/matrix-org/matrix-spec/issues/2164))
+
+**Spec Clarifications**
+
+- Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty. ([#2068](https://github.com/matrix-org/matrix-spec/issues/2068))
+- Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places. ([#2077](https://github.com/matrix-org/matrix-spec/issues/2077))
+- Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+- "Public" rooms in profile look-ups are defined through their join rule and history visibility. ([#2101](https://github.com/matrix-org/matrix-spec/issues/2101))
+- "Public" rooms in user directory queries are defined through their join rule and history visibility. ([#2102](https://github.com/matrix-org/matrix-spec/issues/2102))
+- Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. ([#2104](https://github.com/matrix-org/matrix-spec/issues/2104))
+- "Public" rooms with respect to call invites are defined through their join rule. ([#2106](https://github.com/matrix-org/matrix-spec/issues/2106))
+- "Public" rooms have no specific meaning with respect to moderation policy lists. ([#2107](https://github.com/matrix-org/matrix-spec/issues/2107))
+- "Public" rooms with respect to presence are defined through their join rule. ([#2108](https://github.com/matrix-org/matrix-spec/issues/2108))
+- Spaces are subject to the same access mechanisms as rooms. ([#2109](https://github.com/matrix-org/matrix-spec/issues/2109))
+- Fix various typos throughout the specification. ([#2121](https://github.com/matrix-org/matrix-spec/issues/2121), [#2144](https://github.com/matrix-org/matrix-spec/issues/2144))
+- Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. ([#2140](https://github.com/matrix-org/matrix-spec/issues/2140))
+- Add missing fields in example for `ExportedSessionData`. ([#2154](https://github.com/matrix-org/matrix-spec/issues/2154))
+
+
+## Server-Server API
+
+**Backwards Compatible Changes**
+
+- Add `m.topic` content block to enable rich text in `m.room.topic` events as per [MSC3765](https://github.com/matrix-org/matrix-spec-proposals/pull/3765). ([#2095](https://github.com/matrix-org/matrix-spec/issues/2095))
+- 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). ([#2125](https://github.com/matrix-org/matrix-spec/issues/2125))
+
+**Spec Clarifications**
+
+- Add a note to the invite endpoints that invites to local users may be received twice over federation if the homeserver is already in the room. ([#2067](https://github.com/matrix-org/matrix-spec/issues/2067))
+- Clarify the format of third-party invites, including the fact that identity server public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+- Clarify that auth event of `content.join_authorised_via_users_server` is only necessary for `m.room.member` with a `membership` of `join`. ([#2100](https://github.com/matrix-org/matrix-spec/issues/2100))
+- Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. ([#2104](https://github.com/matrix-org/matrix-spec/issues/2104))
+- Fix various typos throughout the specification. ([#2128](https://github.com/matrix-org/matrix-spec/issues/2128))
+- Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks. ([#2140](https://github.com/matrix-org/matrix-spec/issues/2140))
+
+
+## Application Service API
+
+**Spec Clarifications**
+
+- Clarify in the application service registration schema the `url: null` behaviour. ([#2130](https://github.com/matrix-org/matrix-spec/issues/2130))
+
+
+## Identity Service API
+
+**Spec Clarifications**
+
+- Clarify that public keys can be encoded using standard or URL-safe base64. ([#2083](https://github.com/matrix-org/matrix-spec/issues/2083))
+
+
+## Push Gateway API
+
+No significant changes.
+
+
+## Room Versions
+
+No significant changes.
+
+
+## Appendices
+
+No significant changes.
+
+
+## Internal Changes/Tooling
+
+**Spec Clarifications**
+
+- Adjust margins in rendered endpoints. ([#2081](https://github.com/matrix-org/matrix-spec/issues/2081))
+- Replace Hugo shortcodes in OpenAPI output. ([#2088](https://github.com/matrix-org/matrix-spec/issues/2088))
+- Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks. ([#2115](https://github.com/matrix-org/matrix-spec/issues/2115))
+- Fix the historical info box when generating the historical spec in CI. ([#2123](https://github.com/matrix-org/matrix-spec/issues/2123))
+- Update the header navigation menu with links to modern matrix.org. Contributed by @HarHarLinks. ([#2137](https://github.com/matrix-org/matrix-spec/issues/2137))

content/client-server-api/_index.md

@@ -12,6 +12,12 @@ clients which maintain a full local persistent copy of server state.
 
 ## API Standards
 
+{{% boxes/note %}}
+These standards only apply to the APIs defined in the Matrix specification. APIs
+used by this specification but defined in other specifications, like the [OAuth
+2.0 API](#oauth-20-api), use their own rules.
+{{% /boxes/note %}}
+
 The mandatory baseline for client-server communication in Matrix is
 exchanging JSON objects over HTTP APIs. More efficient transports may be
 specified in future as optional extensions.

content/client-server-api/modules/guest_access.md

@@ -63,7 +63,7 @@ for sending events:
 The following API endpoints are allowed to be accessed by guest accounts
 for their own account maintenance:
 
-* [PUT /profile/{userId}/displayname](#put_matrixclientv3profileuseriddisplayname)
+* [PUT /profile/{userId}/{keyName}](#put_matrixclientv3profileuseridkeyname)
 * [GET /devices](#get_matrixclientv3devices)
 * [GET /devices/{deviceId}](#get_matrixclientv3devicesdeviceid)
 * [PUT /devices/{deviceId}](#put_matrixclientv3devicesdeviceid)

content/client-server-api/modules/sso_login.md

@@ -6,9 +6,10 @@ allow users to log into applications via a single web-based
 authentication portal. Examples include OpenID Connect, "Central
 Authentication Service" (CAS) and SAML.
 
-This module allows a Matrix homeserver to delegate user authentication
+This module allows a Matrix homeserver that supports the [legacy authentication
-to an external authentication server supporting one of these protocols.
+API](#legacy-api) to delegate user authentication to an external authentication
-In this process, there are three systems involved:
+server supporting one of these protocols. In this process, there are three
+systems involved:
 
 -   A Matrix client, using the APIs defined in this specification, which
     is seeking to authenticate a user to a Matrix homeserver.
@@ -24,7 +25,7 @@ used to communicate with the authentication server. Different Matrix
 homeserver implementations might support different SSO protocols.
 
 Clients and homeservers implementing the SSO flow will need to consider
-both [login](#login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
+both [login](#legacy-login) and [user-interactive authentication](#user-interactive-authentication-api). The flow is
 similar in both cases, but there are slight differences.
 
 Typically, SSO systems require a single "callback" URI to be configured

content/proposals.md

@@ -185,6 +185,10 @@ is as follows:
     -   Take care in creating your proposal. Specify your intended
         changes, and give reasoning to back them up. Changes without
         justification will likely be poorly received by the community.
+    -   At the time of creating your draft you will not yet know the PR number, so you
+        should use a placeholder number to name your file and edit that
+        after PR submission. The suggested steps are described in
+        detail [in the proposals guide](https://github.com/matrix-org/matrix-spec-proposals#1-writing-the-proposal).
 -   Fork and make a PR to the
     [matrix-spec-proposals](https://github.com/matrix-org/matrix-spec-proposals) repository.
     The ID of your PR will become the MSC ID for the lifetime of your

data/api/client-server/administrative_contact.yaml

@@ -201,6 +201,11 @@ paths:
 
         Homeservers should prevent the caller from adding a 3PID to their account if it has
         already been added to another user's account on the homeserver.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: add3PID
       security:
         - accessTokenQuery: []

data/api/client-server/capabilities.yaml

@@ -73,11 +73,17 @@ paths:
                           - default
                           - available
                       m.set_displayname:
+                        deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
-                        description: Capability to indicate if the user can change their display name.
+                        description: |
+                          **Deprecated:** Capability to indicate if the user can change their display name.
+                          Refer to `m.profile_fields` for extended profile management.
                       m.set_avatar_url:
+                        deprecated: true
                         $ref: '#/components/schemas/booleanCapability'
-                        description: Capability to indicate if the user can change their avatar.
+                        description: |
+                          **Deprecated:** Capability to indicate if the user can change their avatar.
+                          Refer to `m.profile_fields` for extended profile management.
                       m.3pid_changes:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can change 3PID associations
@@ -86,6 +92,40 @@ paths:
                         $ref: '#/components/schemas/booleanCapability'
                         description: Capability to indicate if the user can generate tokens to log further
                           clients into their account.
+                      m.profile_fields:
+                        x-addedInMatrixVersion: "1.14"
+                        type: object
+                        title: ProfileFieldsCapability
+                        description: Capability to indicate if the user can set or modify extended profile fields via
+                            [`PUT /_matrix/client/v3/profile/{userId}/{keyName}`](/client-server-api/#put_matrixclientv3profileuseridkeyname).
+                          If absent, clients should assume custom profile fields are supported, provided the
+                          response from [`/versions`](/client-server-api/#get_matrixclientversions) indicates
+                          support for a sufficiently recent spec version.
+                        properties:
+                          allowed:
+                            type: array
+                            description: List of allowed additional custom profile field keys. A `*` can be used as a
+                              wildcard to match any sequence of characters. This list takes precedence over the
+                              disallowed list if both are provided.
+                            items:
+                              type: string
+                            example:
+                              - "m.example_field"
+                              - "org.example/job_title"
+                          disallowed:
+                            type: array
+                            description: List of disallowed additional custom profile field keys. A `*` can be used as
+                              a wildcard to match any sequence of characters. Ignored if an allowed list is provided.
+                            items:
+                              type: string
+                            example:
+                              - "org.example.secret_field"
+                          enabled:
+                            type: boolean
+                            description: `true` if the user can set or modify any extended profile fields, `false` otherwise.
+                            example: true
+                        required:
+                          - enabled
               examples:
                 response:
                   value: {

data/api/client-server/cross_signing.yaml

@@ -39,6 +39,11 @@ paths:
         they already exist. Allowing clients to upload the same set of keys more than once
         makes this endpoint idempotent in the case where the response is lost over the network,
         which would otherwise cause a UIA challenge upon retry.
+
+        {{% boxes/warning %}}
+        When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: uploadCrossSigningKeys
       security:
         - accessTokenQuery: []

data/api/client-server/definitions/security.yaml

@@ -14,8 +14,8 @@
 accessTokenQuery:
   type: apiKey
   description: |-
-    **Deprecated.** The `access_token` returned by a call to `/login` or `/register`, as a query
+    **Deprecated.** The `access_token` obtained during [account registration](/client-server-api/#account-registration)
-    parameter.
+    or [login](/client-server-api/#login), as a query parameter.
 
     It can also be the `as_token` of an application service.
   name: access_token
@@ -23,8 +23,8 @@ accessTokenQuery:
 accessTokenBearer:
   type: http
   description: |-
-    The `access_token` returned by a call to `/login` or `/register`, using the
+    The `access_token` obtained during [account registration](/client-server-api/#account-registration)
-    `Authorization: Bearer` header.
+    or [login](/client-server-api/#login), using the `Authorization: Bearer` header.
 
     It can also be the `as_token` of an application service.
 

data/api/client-server/device_management.yaml

@@ -137,6 +137,11 @@ paths:
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         Deletes the given device, and invalidates any access token associated with it.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: deleteDevice
       security:
         - accessTokenQuery: []
@@ -189,6 +194,11 @@ paths:
         This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
         Deletes the given devices, and invalidates any access token associated with them.
+
+        {{% boxes/warning %}}
+        Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
+        via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        {{% /boxes/warning %}}
       operationId: deleteDevices
       security:
         - accessTokenQuery: []

data/api/client-server/profile.yaml

@@ -16,48 +16,105 @@ info:
   title: Matrix Client-Server Profile API
   version: 1.0.0
 paths:
-  "/profile/{userId}/displayname":
+  "/profile/{userId}/{keyName}":
     put:
-      summary: Set the user's display name.
+      x-changedInMatrixVersion:
+        "1.14": Endpoint now accepts variable `keyName` parameter.
+      summary: Set a profile field for a user.
       description: |-
-        This API sets the given user's display name. You must have permission to
+        Set or update a profile field for a user. Must be authenticated with an
-        set this user's display name, e.g. you need to have their `access_token`.
+        access token authorised to make changes. Servers MAY impose size limits
-      operationId: setDisplayName
+        on individual fields, and the total profile MUST be under 64 KiB.
+
+        **Note**: Setting a field to `null` keeps the key but with a `null` value,
+        which some servers may reject. To remove a field completely, use the
+        `DELETE` endpoint instead.
+      operationId: setProfileField
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
-          description: The user whose display name to set.
+          description: The user whose profile field should be set.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
+        - in: path
+          name: keyName
+          description: The profile field key name to set. It must be either
+            `avatar_url`, `displayname`, or a custom field following the
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+          required: true
+          example: "displayname"
+          schema:
+            type: string
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       requestBody:
+        description: A JSON object containing the property whose name matches
+          the `keyName` specified in the URL. See `additionalProperties` for
+          further details.
+        required: true
         content:
           application/json:
             schema:
               type: object
-              example: {
+              minProperties: 1
-                "displayname": "Alice Margatroid"
+              additionalProperties:
-              }
+                description: The JSON object must include a property whose key
-              properties:
+                  matches the `keyName` specified in the URL. For `avatar_url`,
-                displayname:
+                  the value must be an MXC URI string. For `displayname`, the value
-                  type: string
+                  must be a string. For custom keys, any JSON type is allowed -
-                  description: The new display name for this user.
+                  servers may not validate these values, but clients should follow
-        description: The new display name information.
+                  the format defined for that key.
-        required: true
+              example: { "displayname": "Alice Wonderland" }
       responses:
         "200":
-          description: The display name was set.
+          description: The profile field was set.
           content:
             application/json:
               schema:
-                type: object  # empty json object
+                type: object # empty JSON object
               examples:
                 response:
                   value: {}
+        "400":
+          description: The request is malformed, contains invalid JSON, missing
+            a required parameter, specifies an invalid key, or exceeds allowed
+            size limits.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                bad_json:
+                  value:
+                    {
+                      "errcode": "M_BAD_JSON",
+                      "error": "Malformed JSON payload.",
+                    }
+                invalid_key:
+                  value:
+                    {
+                      "errcode": "M_INVALID_PARAM",
+                      "error": "Invalid profile key.",
+                    }
+        "403":
+          description: The server is unwilling to perform the operation, either
+            due to insufficient permissions or because profile modifications
+            are disabled.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                forbidden:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile modification is not permitted.",
+                    }
         "429":
           description: This request was rate-limited.
           content:
@@ -67,98 +124,133 @@ paths:
       tags:
         - User data
     get:
-      summary: Get the user's display name.
+      x-changedInMatrixVersion:
-      description: |-
+        "1.14": Endpoint now accepts variable `keyName` parameter.
-        Get the user's display name. This API may be used to fetch the user's
+      summary: Get a profile field for a user.
-        own displayname or to query the name of other users; either locally or
+      description: Get the value of a profile field for a user. Any individual
-        on remote homeservers.
+        field must be within the total profile limit of 64 KiB.
-      operationId: getDisplayName
+      operationId: getProfileField
       parameters:
         - in: path
           name: userId
-          description: The user whose display name to get.
+          description: The user whose profile field should be returned.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
+        - in: path
+          name: keyName
+          description: The profile field key name to retrieve. It must be either
+            `avatar_url`, `displayname`, or a custom field following the
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+          required: true
+          example: "displayname"
+          schema:
+            type: string
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
       responses:
         "200":
-          description: The display name for this user.
+          description: The profile field value was retrieved.
           content:
             application/json:
               schema:
                 type: object
-                properties:
+                minProperties: 1
-                  displayname:
+                additionalProperties:
-                    type: string
+                  description: The JSON response includes a property whose key
-                    description: The user's display name if they have set one, otherwise not
+                    matches the `keyName` specified in the URL. For `avatar_url`,
-                      present.
+                    the value will be an MXC URI string. For `displayname`, the
+                    value will be a string. For custom keys, any JSON type is
+                    possible - clients should expect the format defined for that key.
               examples:
                 response:
-                  value: {
+                  value: { "displayname": "Alice" }
-                    "displayname": "Alice Margatroid"
-                  }
         "403":
           x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or
+          description: The server is unwilling to disclose whether the user
-            has a display name.
+            exists and/or has the specified profile field.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
+                  value:
-                    "errcode": "M_FORBIDDEN",
+                    {
-                    "error": "Profile lookup is disabled on this homeserver"
+                      "errcode": "M_FORBIDDEN",
-                  }
+                      "error": "Profile lookup is disabled on this homeserver",
+                    }
         "404":
-          description: There is no display name for this user or this user does not exist.
+          description: There is no profile field with this key for this user, or
+            the user does not exist.
       tags:
         - User data
-  "/profile/{userId}/avatar_url":
+    delete:
-    put:
+      x-addedInMatrixVersion: "1.14"
-      summary: Set the user's avatar URL.
+      summary: Remove a profile field from a user.
-      description: |-
+      description: Remove a specific field from a user's profile.
-        This API sets the given user's avatar URL. You must have permission to
+      operationId: deleteProfileField
-        set this user's avatar URL, e.g. you need to have their `access_token`.
-      operationId: setAvatarUrl
       security:
         - accessTokenQuery: []
         - accessTokenBearer: []
       parameters:
         - in: path
           name: userId
-          description: The user whose avatar URL to set.
+          description: The user whose profile field should be deleted.
           required: true
           example: "@alice:example.com"
           schema:
             type: string
-      requestBody:
+        - in: path
-        content:
+          name: keyName
-          application/json:
+          description: The key name of the profile field to delete. It must be either
-            schema:
+            `avatar_url`, `displayname`, or a custom field following the
-              type: object
+            [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
-              example: {
+          required: true
-                "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
+          example: "displayname"
-              }
+          schema:
-              properties:
+            type: string
-                avatar_url:
+            pattern: '^(avatar_url|displayname|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+)$'
-                  type: string
-                  format: uri
-                  description: The new avatar URL for this user.
-        description: The new avatar information.
-        required: true
       responses:
         "200":
-          description: The avatar URL was set.
+          description: The profile field was deleted.
           content:
             application/json:
               schema:
-                type: object  # empty json object
+                type: object
               examples:
                 response:
                   value: {}
+        "400":
+          description: The request is malformed, contains invalid JSON, or
+            specifies an invalid key.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                bad_json:
+                  value:
+                    { "errcode": "M_BAD_JSON", "error": "Malformed request." }
+                invalid_key:
+                  value:
+                    {
+                      "errcode": "M_INVALID_PARAM",
+                      "error": "Invalid profile key.",
+                    }
+        "403":
+          description: The user is not authorised to delete this profile field.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                forbidden:
+                  value:
+                    {
+                      "errcode": "M_FORBIDDEN",
+                      "error": "Profile deletion is not permitted.",
+                    }
         "429":
           description: This request was rate-limited.
           content:
@@ -167,63 +259,15 @@ paths:
                 $ref: definitions/errors/rate_limited.yaml
       tags:
         - User data
-    get:
-      summary: Get the user's avatar URL.
-      description: |-
-        Get the user's avatar URL. This API may be used to fetch the user's
-        own avatar URL or to query the URL of other users; either locally or
-        on remote homeservers.
-      operationId: getAvatarUrl
-      parameters:
-        - in: path
-          name: userId
-          description: The user whose avatar URL to get.
-          required: true
-          example: "@alice:example.com"
-          schema:
-            type: string
-      responses:
-        "200":
-          description: The avatar URL for this user.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  avatar_url:
-                    type: string
-                    format: uri
-                    description: The user's avatar URL if they have set one, otherwise not present.
-              examples:
-                response:
-                  value: {
-                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
-                  }
-        "403":
-          x-addedInMatrixVersion: "1.12"
-          description: The server is unwilling to disclose whether the user exists and/or
-            has an avatar URL.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_FORBIDDEN",
-                    "error": "Profile lookup is disabled on this homeserver"
-                  }
-        "404":
-          description: There is no avatar URL for this user or this user does not exist.
-      tags:
-        - User data
   "/profile/{userId}":
     get:
-      summary: Get this user's profile information.
+      summary: Get all profile information for a user.
       description: |-
-        Get the combined profile information for this user. This API may be used
+        Get the complete profile for a user. The response includes `avatar_url`
-        to fetch the user's own profile information or other users; either
+        and `displayname` (unless set to `null`, as they can only be strings)
-        locally or on remote homeservers.
+        plus any custom profile fields.
+
+        **Note**: The complete profile must be under 64 KiB.
       operationId: getUserProfile
       parameters:
         - in: path
@@ -243,45 +287,49 @@ paths:
                 properties:
                   avatar_url:
                     type: string
-                    format: uri
+                    format: mx-mxc-uri
-                    description: The user's avatar URL if they have set one, otherwise not present.
+                    description: "Avatar URL value (MXC URI format)."
                   displayname:
                     type: string
-                    description: The user's display name if they have set one, otherwise not
+                additionalProperties:
-                      present.
+                  x-addedInMatrixVersion: "1.14"
+                  description: Any additional profile field value; may be any
+                    valid JSON type, with keys following the
+                    [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
               examples:
                 response:
-                  value: {
+                  value:
-                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
+                    {
-                    "displayname": "Alice Margatroid"
+                      "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
-                  }
+                      "displayname": "Alice Margatroid",
+                      "m.example_field": "custom_value",
+                    }
         "403":
           x-addedInMatrixVersion: "1.2"
-          description: The server is unwilling to disclose whether the user exists and/or
+          description: The server is unwilling to disclose whether the user
-            has profile information.
+            exists and/or has profile information.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
+                  value:
-                    "errcode": "M_FORBIDDEN",
+                    {
-                    "error": "Profile lookup is disabled on this homeserver"
+                      "errcode": "M_FORBIDDEN",
-                  }
+                      "error": "Profile lookup is disabled on this homeserver",
+                    }
         "404":
-          description: There is no profile information for this user or this user does not
+          description: There is no profile information for this user or this
-            exist.
+            user does not exist.
           content:
             application/json:
               schema:
                 $ref: definitions/errors/error.yaml
               examples:
                 response:
-                  value: {
+                  value:
-                    "errcode": "M_NOT_FOUND",
+                    { "errcode": "M_NOT_FOUND", "error": "Profile not found" }
-                    "error": "Profile not found"
-                  }
       tags:
         - User data
 servers: