From e7abc7cf41044806e90b54b5535fd458f1066462 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 17 Sep 2025 18:08:56 +0100 Subject: [PATCH 1/6] Add note where an endpoint uses capability negotiation --- .../client-server/administrative_contact.yaml | 48 +++++++++++++++++++ data/api/client-server/login_token.yaml | 12 +++++ .../client-server/password_management.yaml | 16 +++++++ data/api/client-server/profile.yaml | 11 +++++ 4 files changed, 87 insertions(+) diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index 54b91d42..594afaf8 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -99,6 +99,10 @@ paths: has been removed, making this endpoint behave as though it was `false`. This results in this endpoint being an equivalent to `/3pid/bind` rather than dual-purpose. + + This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation). + Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability) + to determine if this endpoint is available. operationId: post3PIDs deprecated: true security: @@ -176,6 +180,18 @@ paths: value: { "submit_url": "https://example.org/path/to/submitToken" } + "400": + description: The 3PID changes capability is not available. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "3PID changes are disabled on this server." + } "403": description: The credentials could not be verified with the identity server. content: @@ -202,6 +218,10 @@ 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. + This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation). + Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability) + to determine if this endpoint is available. + {{% 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). @@ -244,6 +264,18 @@ paths: examples: response: value: {} + "400": + description: The 3PID changes capability is not available. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "3PID changes are disabled on this server." + } "401": description: The homeserver requires additional authentication information. content: @@ -331,6 +363,10 @@ 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. + + This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation). + Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability) + to determine if this endpoint is available. operationId: delete3pidFromAccount security: - accessTokenQuery: [] @@ -389,6 +425,18 @@ paths: example: success required: - id_server_unbind_result + "400": + description: The 3PID changes capability is not available. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "3PID changes are disabled on this server." + } tags: - Account management /account/3pid/unbind: diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml index f14e1a0a..b9c0b35d 100644 --- a/data/api/client-server/login_token.yaml +++ b/data/api/client-server/login_token.yaml @@ -110,6 +110,18 @@ paths: application/json: schema: $ref: definitions/auth_response.yaml + "404": + description: The get login token capability is not available. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNRECOGNIZED", + "error": "The get login token capability is not available." + } "429": description: This request was rate-limited. content: diff --git a/data/api/client-server/password_management.yaml b/data/api/client-server/password_management.yaml index bf310ff9..66f63db0 100644 --- a/data/api/client-server/password_management.yaml +++ b/data/api/client-server/password_management.yaml @@ -34,6 +34,10 @@ paths: valid access token is provided. The homeserver SHOULD NOT revoke the access token provided in the request. Whether other access tokens for the user are revoked depends on the request parameters. + + This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation). + Clients SHOULD check the value of the [`m.change_password` capability](/client-server-api/#mchange_password-capability) + to determine if this endpoint is available. security: - {} - accessTokenQuery: [] @@ -82,6 +86,18 @@ paths: application/json: schema: $ref: definitions/auth_response.yaml + "403": + description: The password change capability is not available. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Password change is disabled." + } "429": description: This request was rate-limited. content: diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index 9f872fe8..13e0fa39 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -29,6 +29,11 @@ paths: Servers MAY reject `null` values. Servers that accept `null` values SHOULD store them rather than treating `null` as a deletion request. Clients that want to delete a field, including its key and value, SHOULD use the `DELETE` endpoint instead. + + This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation) + depending on the `keyName`. + For the `displayname` key, clients SHOULD check the value of the [`m.set_displayname` capability](/client-server-api/#m.set_displayname-capability). + For the `avatar_url` key, clients SHOULD check the value of the [`m.set_avatar_url` capability](/client-server-api/#m.set_avatar_url-capability). operationId: setProfileField security: - accessTokenQuery: [] @@ -116,6 +121,12 @@ paths: "errcode": "M_INVALID_PARAM", "error": "Invalid profile key.", } + capability_disabled: + value: + { + "errcode": "M_FORBIDDEN", + "error": "Profile modification is disabled on this homeserver.", + } "403": description: The server is unwilling to perform the operation, either due to insufficient permissions or because profile modifications From 82e7b625e09117874dc95ecc2390677732a04f8d Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 17 Sep 2025 18:11:10 +0100 Subject: [PATCH 2/6] Changelog --- changelogs/client_server/newsfragments/2212.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/2212.clarification diff --git a/changelogs/client_server/newsfragments/2212.clarification b/changelogs/client_server/newsfragments/2212.clarification new file mode 100644 index 00000000..1e1baa39 --- /dev/null +++ b/changelogs/client_server/newsfragments/2212.clarification @@ -0,0 +1 @@ +Add note to each endpoint that uses capability negotiation and document expected response when the capability is not available. From bf08e68af78c875d823b25f59691bf1ec85907de Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 17 Sep 2025 18:19:34 +0100 Subject: [PATCH 3/6] Fix links --- data/api/client-server/profile.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index 13e0fa39..c426059f 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -32,8 +32,8 @@ paths: This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation) depending on the `keyName`. - For the `displayname` key, clients SHOULD check the value of the [`m.set_displayname` capability](/client-server-api/#m.set_displayname-capability). - For the `avatar_url` key, clients SHOULD check the value of the [`m.set_avatar_url` capability](/client-server-api/#m.set_avatar_url-capability). + For the `displayname` key, clients SHOULD check the value of the [`m.set_displayname` capability](/client-server-api/#mset_displayname-capability). + For the `avatar_url` key, clients SHOULD check the value of the [`m.set_avatar_url` capability](/client-server-api/#mset_avatar_url-capability). operationId: setProfileField security: - accessTokenQuery: [] From 8cb0b3e7f6e0cd0844c1fba93a0555b7a5f5d64f Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Thu, 25 Sep 2025 09:04:41 +0100 Subject: [PATCH 4/6] Update data/api/client-server/profile.yaml Co-authored-by: Johannes Marbach --- data/api/client-server/profile.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index c426059f..6814ccb5 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -31,9 +31,9 @@ paths: field, including its key and value, SHOULD use the `DELETE` endpoint instead. This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation) - depending on the `keyName`. - For the `displayname` key, clients SHOULD check the value of the [`m.set_displayname` capability](/client-server-api/#mset_displayname-capability). - For the `avatar_url` key, clients SHOULD check the value of the [`m.set_avatar_url` capability](/client-server-api/#mset_avatar_url-capability). + depending on the `keyName`. Clients SHOULD check the value of the + [`m.profile_fields` capability](/client-server-api/#mprofile_fields-capability) to detect + which `keyName`s they are allowed to modify. operationId: setProfileField security: - accessTokenQuery: [] From 2a8a6d78330be86655626ba128278eeeb8ad9c6a Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 6 Oct 2025 10:57:53 +0100 Subject: [PATCH 5/6] Remove content that is now in #2223 --- data/api/client-server/administrative_contact.yaml | 12 ------------ data/api/client-server/password_management.yaml | 4 ---- data/api/client-server/profile.yaml | 5 ----- 3 files changed, 21 deletions(-) diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index 594afaf8..bebbbcb8 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -99,10 +99,6 @@ paths: has been removed, making this endpoint behave as though it was `false`. This results in this endpoint being an equivalent to `/3pid/bind` rather than dual-purpose. - - This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation). - Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability) - to determine if this endpoint is available. operationId: post3PIDs deprecated: true security: @@ -218,10 +214,6 @@ 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. - This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation). - Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability) - to determine if this endpoint is available. - {{% 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). @@ -363,10 +355,6 @@ 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. - - This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation). - Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability) - to determine if this endpoint is available. operationId: delete3pidFromAccount security: - accessTokenQuery: [] diff --git a/data/api/client-server/password_management.yaml b/data/api/client-server/password_management.yaml index 66f63db0..52c81a5e 100644 --- a/data/api/client-server/password_management.yaml +++ b/data/api/client-server/password_management.yaml @@ -34,10 +34,6 @@ paths: valid access token is provided. The homeserver SHOULD NOT revoke the access token provided in the request. Whether other access tokens for the user are revoked depends on the request parameters. - - This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation). - Clients SHOULD check the value of the [`m.change_password` capability](/client-server-api/#mchange_password-capability) - to determine if this endpoint is available. security: - {} - accessTokenQuery: [] diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index 6814ccb5..fef6b702 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -29,11 +29,6 @@ paths: Servers MAY reject `null` values. Servers that accept `null` values SHOULD store them rather than treating `null` as a deletion request. Clients that want to delete a field, including its key and value, SHOULD use the `DELETE` endpoint instead. - - This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation) - depending on the `keyName`. Clients SHOULD check the value of the - [`m.profile_fields` capability](/client-server-api/#mprofile_fields-capability) to detect - which `keyName`s they are allowed to modify. operationId: setProfileField security: - accessTokenQuery: [] From 205fa06076cc54ddb4821ed3f7e345c19420feb0 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 6 Oct 2025 11:14:55 +0100 Subject: [PATCH 6/6] Update changelog --- changelogs/client_server/newsfragments/2212.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/2212.clarification b/changelogs/client_server/newsfragments/2212.clarification index 1e1baa39..0b033b2b 100644 --- a/changelogs/client_server/newsfragments/2212.clarification +++ b/changelogs/client_server/newsfragments/2212.clarification @@ -1 +1 @@ -Add note to each endpoint that uses capability negotiation and document expected response when the capability is not available. +Add example to each endpoint when the capability is not available.