Merge pull request #346 from matrix-org/dbkr/more_requesttokens

Add requestToken endpoints

api/client-server/administrative_contact.yaml

@@ -119,3 +119,16 @@ paths:
               }
       tags:
         - User data
+  "/account/3pid/email/requestToken":
+    post:
+      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
+        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 the HS API
+        |/register/email/requestToken|_ endpoint.
+      responses:
+        200:
+          description: An email was sent to the given address

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
@@ -242,3 +242,24 @@ 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 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
+        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 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

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.