From ead5648b8c54322680f4e3d01a5419c85f8ef96a Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 7 Jul 2016 14:52:45 +0100 Subject: [PATCH 1/8] Add requestToken endpoints For password reset and 3pid adding --- api/client-server/administrative_contact.yaml | 9 +++++++++ api/client-server/registration.yaml | 13 +++++++++++++ specification/client_server_api.rst | 3 +++ 3 files changed, 25 insertions(+) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 02057758..a6e060e4 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -119,3 +119,12 @@ paths: } tags: - User data + "/account/3pid/email/requestToken": + post: + summary: Requests a validation token be sent to the given email address + description: |- + Proxies the identity server API ``validate/email/requestToken``, but + first checks that the given email address is not already associated + with an account on this Home Server. This API should be used to request + validation tokens when adding an email address to an account. This API + behaves identically to `/register/email/requestToken` diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index f2e50390..f802686f 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -242,3 +242,16 @@ paths: "$ref": "definitions/error.yaml" tags: - User data + "/account/password/email/requestToken": + post: + summary: Requests a validation token be sent to the given email address + description: |- + Proxies the identity server API ``validate/email/requestToken``, but + first checks that the given email address is associated with an account + on this Home Server. This API should be used to request + validation tokens when authenticating for the + `account/password` endpoint. This API behaves identically to + `/register/email/requestToken` except that `M_THREEPID_NOT_FOUND` may be + returned if no account matching the given email address could be found. + The server may instead send an email to the given address prompting + the user to create an account. `M_THREEPID_IN_USE` may not be returned. diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 1e9feaff..00024e42 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -116,6 +116,9 @@ Some requests have unique error codes: :``M_THREEPID_IN_USE``: Sent when a threepid given to an API cannot be used because the same threepid is already in use. +:``M_THREEPID_NOT_FOUND``: + Sent when a threepid given to an API cannot be used because no record matching the threepid was found + :``M_SERVER_NOT_TRUSTED``: The client's request used a third party server, eg. ID server, that this server does not trust. From d74a320edd620ae30837ba7f930916a28b99725e Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 7 Jul 2016 14:58:05 +0100 Subject: [PATCH 2/8] Stray tab --- api/client-server/administrative_contact.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index a6e060e4..aef8edb6 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -127,4 +127,4 @@ paths: first checks that the given email address is not already associated with an account on this Home Server. This API should be used to request validation tokens when adding an email address to an account. This API - behaves identically to `/register/email/requestToken` + behaves identically to `/register/email/requestToken` From 191cb08a3a9dad19ffc8e71b132571cf4001d3a2 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 7 Jul 2016 15:00:27 +0100 Subject: [PATCH 3/8] Add response section otherwise the checker fails --- api/client-server/administrative_contact.yaml | 3 +++ api/client-server/registration.yaml | 3 +++ 2 files changed, 6 insertions(+) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index aef8edb6..a7bed31f 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -128,3 +128,6 @@ paths: with an account on this Home Server. This API should be used to request validation tokens when adding an email address to an account. This API behaves identically to `/register/email/requestToken` + responses: + 200: + description: An email was sent to the given address diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index f802686f..8fa09b75 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -255,3 +255,6 @@ paths: returned if no account matching the given email address could be found. The server may instead send an email to the given address prompting the user to create an account. `M_THREEPID_IN_USE` may not be returned. + responses: + 200: + description: An email was sent to the given address From 4812be9142753b2966b6eaa9bb20a58801672d62 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 7 Jul 2016 15:58:20 +0100 Subject: [PATCH 4/8] Missing . --- specification/client_server_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 00024e42..17a86922 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -117,7 +117,7 @@ Some requests have unique error codes: Sent when a threepid given to an API cannot be used because the same threepid is already in use. :``M_THREEPID_NOT_FOUND``: - Sent when a threepid given to an API cannot be used because no record matching the threepid was found + Sent when a threepid given to an API cannot be used because no record matching the threepid was found. :``M_SERVER_NOT_TRUSTED``: The client's request used a third party server, eg. ID server, that this server does not trust. From 86db820bb172d2dc96df4c8c3382a6d684af98e9 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 7 Jul 2016 16:05:21 +0100 Subject: [PATCH 5/8] Expand on summaries for requestToken endpoints --- api/client-server/administrative_contact.yaml | 2 +- api/client-server/registration.yaml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index a7bed31f..fabb2ac9 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -121,7 +121,7 @@ paths: - User data "/account/3pid/email/requestToken": post: - summary: Requests a validation token be sent to the given email address + summary: Requests a validation token be sent to the given email address for the purpose of adding an email address to an account description: |- Proxies the identity server API ``validate/email/requestToken``, but first checks that the given email address is not already associated diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 8fa09b75..a9bd3fe0 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -134,7 +134,7 @@ paths: - User data "/register/email/requestToken": post: - summary: Requests a validation token be sent to the given email address + summary: Requests a validation token be sent to the given email address for the purpose of registering an account description: |- Proxies the identity server API ``validate/email/requestToken``, but first checks that the given email address is not already associated @@ -244,7 +244,7 @@ paths: - User data "/account/password/email/requestToken": post: - summary: Requests a validation token be sent to the given email address + summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password description: |- Proxies the identity server API ``validate/email/requestToken``, but first checks that the given email address is associated with an account From c109da5b78d075c150c75d3b281237294d746520 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 7 Jul 2016 17:07:38 +0100 Subject: [PATCH 6/8] Attempt to make things clearer --- api/client-server/administrative_contact.yaml | 4 ++-- api/client-server/registration.yaml | 11 ++++++----- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index fabb2ac9..d3821d04 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -126,8 +126,8 @@ paths: Proxies the identity server API ``validate/email/requestToken``, but first checks that the given email address is not already associated with an account on this Home Server. This API should be used to request - validation tokens when adding an email address to an account. This API - behaves identically to `/register/email/requestToken` + validation tokens when adding an email address to an account. This API's + parameters and response is identical to that of `/register/email/requestToken`. responses: 200: description: An email was sent to the given address diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index a9bd3fe0..70d4ee07 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -250,11 +250,12 @@ paths: first checks that the given email address is associated with an account on this Home Server. This API should be used to request validation tokens when authenticating for the - `account/password` endpoint. This API behaves identically to - `/register/email/requestToken` except that `M_THREEPID_NOT_FOUND` may be - returned if no account matching the given email address could be found. - The server may instead send an email to the given address prompting - the user to create an account. `M_THREEPID_IN_USE` may not be returned. + `account/password` endpoint. This API's parameters and response are + identical to that of `/register/email/requestToken` except that + `M_THREEPID_NOT_FOUND` may be returned if no account matching the + given email address could be found. The server may instead send an + email to the given address prompting the user to create an account. + `M_THREEPID_IN_USE` may not be returned. responses: 200: description: An email was sent to the given address From 7c8651480a3393b00e0cb88c85a6e571817f132e Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 8 Jul 2016 11:56:23 +0100 Subject: [PATCH 7/8] Some PR feedback corrections Including adding a hyperlink, although this requires a separate fix that I'll do on a different branch --- api/client-server/administrative_contact.yaml | 9 +++++++-- api/client-server/registration.yaml | 4 +++- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index d3821d04..7c0f1329 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -124,10 +124,15 @@ paths: summary: Requests a validation token be sent to the given email address for the purpose of adding an email address to an account description: |- Proxies the identity server API ``validate/email/requestToken``, but - first checks that the given email address is not already associated + first checks that the given email address is **not** already associated with an account on this Home Server. This API should be used to request validation tokens when adding an email address to an account. This API's - parameters and response is identical to that of `/register/email/requestToken`. + parameters and response is identical to that of the HS API + |/register/email/requestToken|_ endpoint. + + .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` + + .. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken responses: 200: description: An email was sent to the given address diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 70d4ee07..7c675e5f 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -136,6 +136,8 @@ paths: post: summary: Requests a validation token be sent to the given email address for the purpose of registering an account description: |- + .. _register-email-requestToken-endpoint: + Proxies the identity server API ``validate/email/requestToken``, but first checks that the given email address is not already associated with an account on this Home Server. Note that, for consistency, @@ -247,7 +249,7 @@ paths: summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password description: |- Proxies the identity server API ``validate/email/requestToken``, but - first checks that the given email address is associated with an account + first checks that the given email address **is** associated with an account on this Home Server. This API should be used to request validation tokens when authenticating for the `account/password` endpoint. This API's parameters and response are From e91214e78e9b4841f87de9f46cae577c46cd0c9c Mon Sep 17 00:00:00 2001 From: David Baker Date: Fri, 8 Jul 2016 14:26:18 +0100 Subject: [PATCH 8/8] More links Also remove now redundant anchor --- api/client-server/administrative_contact.yaml | 4 ---- api/client-server/registration.yaml | 8 +++++--- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 7c0f1329..003b9f82 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -129,10 +129,6 @@ paths: validation tokens when adding an email address to an account. This API's parameters and response is identical to that of the HS API |/register/email/requestToken|_ endpoint. - - .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` - - .. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken responses: 200: description: An email was sent to the given address diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 7c675e5f..0e2bc21b 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -136,8 +136,6 @@ paths: post: summary: Requests a validation token be sent to the given email address for the purpose of registering an account description: |- - .. _register-email-requestToken-endpoint: - Proxies the identity server API ``validate/email/requestToken``, but first checks that the given email address is not already associated with an account on this Home Server. Note that, for consistency, @@ -253,11 +251,15 @@ paths: on this Home Server. This API should be used to request validation tokens when authenticating for the `account/password` endpoint. This API's parameters and response are - identical to that of `/register/email/requestToken` except that + identical to that of the HS API |/register/email/requestToken|_ except that `M_THREEPID_NOT_FOUND` may be returned if no account matching the given email address could be found. The server may instead send an email to the given address prompting the user to create an account. `M_THREEPID_IN_USE` may not be returned. + + .. |/register/email/requestToken| replace:: ``/register/email/requestToken`` + + .. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken responses: 200: description: An email was sent to the given address