From adcd6ba4a2b607454fb594004548f54e391cb2c7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <zecakeh@tedomum.fr>
Date: Thu, 18 Dec 2025 10:37:12 +0100
Subject: [PATCH] Add instructions on endpoints that should no longer be used
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 content/client-server-api/_index.md              |  5 +++++
 data/api/client-server/account_deactivation.yaml |  8 ++++++++
 data/api/client-server/device_management.yaml    | 14 ++++++++++++++
 data/api/client-server/registration.yaml         |  8 ++++++++
 4 files changed, 35 insertions(+)

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 64b1ee01..82aeaac8 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -1520,6 +1520,11 @@ client supports it, the client should redirect the user to the
 is complete, the client will need to submit a `/login` request matching
 `m.login.token`.
 
+{{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+MUST only offer the `m.login.sso` flow to the user when `oauth_aware_preferred`
+is set to `true` and MUST add the `action=login` parameter to the SSO redirect
+endpoint.
+
 {{% added-in v="1.7" %}} Already-authenticated clients can additionally generate
 a token for their user ID if supported by the homeserver using
 [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).
diff --git a/data/api/client-server/account_deactivation.yaml b/data/api/client-server/account_deactivation.yaml
index 467af659..c7f68f67 100644
--- a/data/api/client-server/account_deactivation.yaml
+++ b/data/api/client-server/account_deactivation.yaml
@@ -35,6 +35,14 @@ paths:
         Unlike other endpoints, this endpoint does not take an `id_access_token`
         parameter because the homeserver is expected to sign the request to the
         identity server instead.
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available, and MAY use the `action=org.matrix.account_deactivate`
+        parameter.
+        {{% /boxes/warning %}}
       security:
         - {}
         - accessTokenQuery: []
diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml
index 1b245e78..da54c111 100644
--- a/data/api/client-server/device_management.yaml
+++ b/data/api/client-server/device_management.yaml
@@ -142,6 +142,13 @@ paths:
         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 %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available, with the `action=org.matrix.device_delete` and `device_id={deviceId}` parameters.
+        {{% /boxes/warning %}}
       operationId: deleteDevice
       security:
         - accessTokenQuery: []
@@ -199,6 +206,13 @@ paths:
         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 %}}
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
+        Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
+        if available.
+        {{% /boxes/warning %}}
       operationId: deleteDevices
       security:
         - accessTokenQuery: []
diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml
index e7ede561..535689da 100644
--- a/data/api/client-server/registration.yaml
+++ b/data/api/client-server/registration.yaml
@@ -60,6 +60,14 @@ paths:
 
         Any user ID returned by this API must conform to the grammar given in the
         [Matrix specification](/appendices/#user-identifiers).
+
+        {{% boxes/warning %}}
+        {{% added-in v="1.17" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
+        MUST NOT use this endpoint when the server offers the [`m.login.sso`
+        authentication flow](/client-server-api/#client-login-via-sso) with
+        `oauth_aware_preferred` set to `true`. Instead they MUST add the
+        `action=register` parameter to the SSO redirect endpoint.
+        {{% /boxes/warning %}}
       operationId: register
       parameters:
         - in: query