From b0194a3016e84f27ab25873221e6059e002d8847 Mon Sep 17 00:00:00 2001
From: David Baker <dave@matrix.org>
Date: Thu, 30 Jun 2016 14:50:17 +0100
Subject: [PATCH] Spec for endpoint-specific 3pid verification token

As per proposal https://docs.google.com/document/d/13mapDbaOnbob9ZYRDiGm1YbeZhFOBj_R1OvgBA9pA5s/edit?pref=2&pli=1#
---
 api/client-server/registration.yaml    | 52 +++++++++++++++++++++++++-
 specification/identity_service_api.rst |  5 +++
 2 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index e5875225..a67ce2a1 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -132,9 +132,59 @@ paths:
             "$ref": "definitions/error.yaml"
       tags:
         - User data
+  "/register/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
+        additionally inform the user if the given email is already associated
+        with an account on this Home Server. Note that, for consistency,
+        this API takes JSON objects, though the Identity Server API takes
+        ``x-www-form-urlencoded`` parameters. See the Identity Server API for
+        further information, including the full list of response coes.
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              client_secret:
+                type: string
+                description: Client-generated secret string used to protect this session
+                example: "this_is_my_secret_string"
+              email:
+                type: string
+                description: The email address
+                example: "example@example.com"
+              send_attempt:
+                type: number
+                description: Used to distinguish protocol level retries from requests to re-send the email.
+                example: "1"
+            required: ["client_secret", "email", "send_attempt"]
+      responses:
+        200:
+          description: |-
+            An email has been sent to the specified address.
+            Note that this may be an email containing the validation token or it may be informing
+            the user of an error.
+          examples:
+            application/json: "{}"
+          schema:
+            type: object
+        400:
+          description: |-
+            Returns an error object indicating the nature of the error. A Home Server may use
+            ``M_THREEPID_IN_USE`` to inform the user that the email address is already registered
+            to an account on this server, however, if the home server has the ability to send email,
+            it is recommended that the server instead send an email to the user with instructions
+            on how to reset their password.
+          examples:
+            application/json: '{"errcode": "M_THREEPID_IN_USE", "error": "The specified address is already in use"}'
+          schema:
+            type: object
   "/account/password":
     post:
-      summary: Changes a user's password.
+      summary: "Changes a user's password."
       description: |-
         Changes the password for an account on this homeserver.
 
diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst
index 0aa34343..d6f5d324 100644
--- a/specification/identity_service_api.rst
+++ b/specification/identity_service_api.rst
@@ -124,6 +124,11 @@ This is to avoid repeatedly sending the same email in the case of request
 retries between the POSTing user and the identity service. The client should
 increment this value if they desire a new email (e.g. a reminder) to be sent.
 
+Note that Home Servers offer APIs that proxy this API, adding additional
+behaviour on top, for example, ``/register/email/requestToken`` is designed
+specifically for use when registering an account and therefore will inform
+the user if the email address given is already registered on the server.
+
 Validating ownership of an email
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~