From 064e8f1411be3468d1dcbd314f94edc115481604 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Fri, 19 Dec 2025 11:19:42 +0100 Subject: [PATCH 1/5] Spec Additional Error Codes for submitToken endpoint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../definitions/request_token_response.yaml | 18 ++++++++++++------ data/api/identity/v2_email_associations.yaml | 19 +++++++++++++++++++ data/api/identity/v2_phone_associations.yaml | 19 +++++++++++++++++++ 3 files changed, 50 insertions(+), 6 deletions(-) diff --git a/data/api/client-server/definitions/request_token_response.yaml b/data/api/client-server/definitions/request_token_response.yaml index 0f8c8cab..2f4216aa 100644 --- a/data/api/client-server/definitions/request_token_response.yaml +++ b/data/api/client-server/definitions/request_token_response.yaml @@ -24,16 +24,22 @@ properties: submit_url: type: string format: uri + x-changedInMatrixVersion: + "1.18": |- + The URL has the same request and response parameters and error codes as + the Identity Service API's endpoint. description: |- An optional field containing a URL where the client must submit the - validation token to, with identical parameters to the Identity Service - API's `POST /validate/email/submitToken` endpoint (without the requirement - for an access token). The homeserver must send this token to the user (if - applicable), who should then be prompted to provide it to the client. + validation token, with identical request and response parameters and error + codes to the Identity Service API's + [`POST /_matrix/identity/v2/validate/email/submitToken`](/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) + endpoint (without the requirement for an access token). The homeserver + must send this token to the user (if applicable), who should then be + prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement provided the homeserver - advertises this specification version in the `/versions` response - (ie: r0.5.0). + advertises this specification version in the [`GET /versions`](/client-server-api/#get_matrixclientversions) + response (ie: r0.5.0). example: "https://example.org/path/to/submitToken" required: ['sid'] diff --git a/data/api/identity/v2_email_associations.yaml b/data/api/identity/v2_email_associations.yaml index 81f4486c..e37c9725 100644 --- a/data/api/identity/v2_email_associations.yaml +++ b/data/api/identity/v2_email_associations.yaml @@ -153,6 +153,25 @@ paths: value: { "success": true } + "400": + x-addedInMatrixVersion: "1.18" + description: | + An error occurred. Some possible errors are: + + - `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is + incorrect. + - `M_INVALID_PARAM`: One of the supplied parameters is not valid. + - `M_SESSION_EXPIRED`: The validation session in question has expired. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOKEN_INCORRECT", + "error": "The token is incorrect" + } "403": description: | The user must do something in order to use this endpoint. One example diff --git a/data/api/identity/v2_phone_associations.yaml b/data/api/identity/v2_phone_associations.yaml index b985a972..047cbc40 100644 --- a/data/api/identity/v2_phone_associations.yaml +++ b/data/api/identity/v2_phone_associations.yaml @@ -155,6 +155,25 @@ paths: value: { "success": true } + "400": + x-addedInMatrixVersion: "1.18" + description: | + An error occurred. Some possible errors are: + + - `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is + incorrect. + - `M_INVALID_PARAM`: One of the supplied parameters is not valid. + - `M_SESSION_EXPIRED`: The validation session in question has expired. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOKEN_INCORRECT", + "error": "The token is incorrect" + } "403": description: | The user must do something in order to use this endpoint. One example From a6fb075d92adef5faa6d89bba618f36f4f79a344 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Fri, 19 Dec 2025 11:28:01 +0100 Subject: [PATCH 2/5] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/2277.clarification | 3 +++ changelogs/identity_service/newsfragments/2277.clarification | 3 +++ 2 files changed, 6 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2277.clarification create mode 100644 changelogs/identity_service/newsfragments/2277.clarification diff --git a/changelogs/client_server/newsfragments/2277.clarification b/changelogs/client_server/newsfragments/2277.clarification new file mode 100644 index 00000000..bf818eaf --- /dev/null +++ b/changelogs/client_server/newsfragments/2277.clarification @@ -0,0 +1,3 @@ +The optional `submit_url` response parameter of the `/requestToken` endpoints uses the same request +and response parameters and error codes as the Identity Service API's `POST /_matrix/identity/v2/validate/email/submitToken`, +as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183). diff --git a/changelogs/identity_service/newsfragments/2277.clarification b/changelogs/identity_service/newsfragments/2277.clarification new file mode 100644 index 00000000..58510ecf --- /dev/null +++ b/changelogs/identity_service/newsfragments/2277.clarification @@ -0,0 +1,3 @@ +Clarify the error codes that can be returned with a 400 HTTP status code by the `POST /_matrix/identity/v2/validate/email/submitToken` +and `POST /_matrix/identity/v2/validate/msisdn/submitToken` endpoints, introducing the `M_TOKEN_INCORRECT` +error code, as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183). From 611ba3b4f9f1fac9ccacf4a3a64079bdae10afa2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 15 Jan 2026 11:12:59 +0100 Subject: [PATCH 3/5] Fix added in position MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/identity/v2_email_associations.yaml | 7 +++---- data/api/identity/v2_phone_associations.yaml | 7 +++---- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/data/api/identity/v2_email_associations.yaml b/data/api/identity/v2_email_associations.yaml index e37c9725..2f643f31 100644 --- a/data/api/identity/v2_email_associations.yaml +++ b/data/api/identity/v2_email_associations.yaml @@ -154,14 +154,13 @@ paths: "success": true } "400": - x-addedInMatrixVersion: "1.18" description: | An error occurred. Some possible errors are: - - `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is + - **[Added in v1.18]** `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is incorrect. - - `M_INVALID_PARAM`: One of the supplied parameters is not valid. - - `M_SESSION_EXPIRED`: The validation session in question has expired. + - **[Added in v1.18]** `M_INVALID_PARAM`: One of the supplied parameters is not valid. + - **[Added in v1.18]** `M_SESSION_EXPIRED`: The validation session in question has expired. content: application/json: schema: diff --git a/data/api/identity/v2_phone_associations.yaml b/data/api/identity/v2_phone_associations.yaml index 047cbc40..eb3fd344 100644 --- a/data/api/identity/v2_phone_associations.yaml +++ b/data/api/identity/v2_phone_associations.yaml @@ -156,14 +156,13 @@ paths: "success": true } "400": - x-addedInMatrixVersion: "1.18" description: | An error occurred. Some possible errors are: - - `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is + - **[Added in v1.18]** `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is incorrect. - - `M_INVALID_PARAM`: One of the supplied parameters is not valid. - - `M_SESSION_EXPIRED`: The validation session in question has expired. + - **[Added in v1.18]** `M_INVALID_PARAM`: One of the supplied parameters is not valid. + - **[Added in v1.18]** `M_SESSION_EXPIRED`: The validation session in question has expired. content: application/json: schema: From 4297109c1198ba7a5d50a8072d07fd49465c810b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 15 Jan 2026 11:19:31 +0100 Subject: [PATCH 4/5] Apply sugggestions to RequestTokenResponse MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../client-server/definitions/request_token_response.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/data/api/client-server/definitions/request_token_response.yaml b/data/api/client-server/definitions/request_token_response.yaml index 2f4216aa..67afc6ab 100644 --- a/data/api/client-server/definitions/request_token_response.yaml +++ b/data/api/client-server/definitions/request_token_response.yaml @@ -33,13 +33,14 @@ properties: validation token, with identical request and response parameters and error codes to the Identity Service API's [`POST /_matrix/identity/v2/validate/email/submitToken`](/identity-service-api/#post_matrixidentityv2validateemailsubmittoken) - endpoint (without the requirement for an access token). The homeserver + and [`POST /_matrix/identity/v2/validate/msisdn/submitToken`](/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken) + endpoints (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client. If this field is not present, the client can assume that verification will happen without the client's involvement provided the homeserver - advertises this specification version in the [`GET /versions`](/client-server-api/#get_matrixclientversions) + advertises a sufficiently recent version in the [`GET /versions`](/client-server-api/#get_matrixclientversions) response (ie: r0.5.0). example: "https://example.org/path/to/submitToken" required: ['sid'] From f5c1b24bd89e843049fadfa0441aeb3cd37590f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Thu, 15 Jan 2026 11:25:12 +0100 Subject: [PATCH 5/5] Use added-in shortcode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/identity/v2_email_associations.yaml | 6 +++--- data/api/identity/v2_phone_associations.yaml | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/data/api/identity/v2_email_associations.yaml b/data/api/identity/v2_email_associations.yaml index 2f643f31..da6c9c1b 100644 --- a/data/api/identity/v2_email_associations.yaml +++ b/data/api/identity/v2_email_associations.yaml @@ -157,10 +157,10 @@ paths: description: | An error occurred. Some possible errors are: - - **[Added in v1.18]** `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is + - {{% added-in v="1.18" %}} `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is incorrect. - - **[Added in v1.18]** `M_INVALID_PARAM`: One of the supplied parameters is not valid. - - **[Added in v1.18]** `M_SESSION_EXPIRED`: The validation session in question has expired. + - {{% added-in v="1.18" %}} `M_INVALID_PARAM`: One of the supplied parameters is not valid. + - {{% added-in v="1.18" %}} `M_SESSION_EXPIRED`: The validation session in question has expired. content: application/json: schema: diff --git a/data/api/identity/v2_phone_associations.yaml b/data/api/identity/v2_phone_associations.yaml index eb3fd344..5ebf58bc 100644 --- a/data/api/identity/v2_phone_associations.yaml +++ b/data/api/identity/v2_phone_associations.yaml @@ -159,10 +159,10 @@ paths: description: | An error occurred. Some possible errors are: - - **[Added in v1.18]** `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is + - {{% added-in v="1.18" %}} `M_TOKEN_INCORRECT`: The token that the user entered to validate the session is incorrect. - - **[Added in v1.18]** `M_INVALID_PARAM`: One of the supplied parameters is not valid. - - **[Added in v1.18]** `M_SESSION_EXPIRED`: The validation session in question has expired. + - {{% added-in v="1.18" %}} `M_INVALID_PARAM`: One of the supplied parameters is not valid. + - {{% added-in v="1.18" %}} `M_SESSION_EXPIRED`: The validation session in question has expired. content: application/json: schema: