Merge remote-tracking branch 'origin/master' into rav/is_token_grammar

api/client-server/administrative_contact.yaml

@@ -191,7 +191,7 @@ paths:
         first checks that the given email address is **not** already associated
         with an account on this homeserver. 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 |/register/email/requestToken|_
+        parameters and response are identical to that of the |/register/email/requestToken|_
         endpoint.
       operationId: requestTokenTo3PIDEmail
       parameters:
@@ -217,9 +217,8 @@ paths:
             $ref: "../identity/definitions/sid.yaml"
         403:
           description: |-
-            The homeserver does not permit the user from having the third party
+            The homeserver does not allow the third party identifier as a
-            identifier as a contact option. This does not prevent the identity
+            contact option.
-            service from binding the third party identifier, however.
           schema:
             $ref: "definitions/errors/error.yaml"
           examples:
@@ -229,14 +228,14 @@ paths:
             }
         400:
           description: |-
-            The homeserver was unable to locate a user with the third party identifier
+            The third party identifier is already in use on the homeserver, or
-            already bound, or the request was invalid.
+            the request was invalid.
           schema:
             $ref: "definitions/errors/error.yaml"
           examples:
             application/json: {
-              "errcode": "M_THREEPID_NOT_FOUND",
+              "errcode": "M_THREEPID_IN_USE",
-              "error": "Third party identifier not found"
+              "error": "Third party identifier already in use"
             }
   "/account/3pid/msisdn/requestToken":
     post:
@@ -246,7 +245,7 @@ paths:
         first checks that the given phone number is **not** already associated
         with an account on this Home Server. This API should be used to request
         validation tokens when adding a phone number to an account. This API's
-        parameters and response is identical to that of the |/register/msisdn/requestToken|_
+        parameters and response are identical to that of the |/register/msisdn/requestToken|_
         endpoint.
       operationId: requestTokenTo3PIDMSISDN
       parameters:
@@ -272,9 +271,8 @@ paths:
             $ref: "../identity/definitions/sid.yaml"
         403:
           description: |-
-            The homeserver does not permit the user from having the third party
+            The homeserver does not allow the third party identifier as a
-            identifier as a contact option. This does not prevent the identity
+            contact option.
-            service from binding the third party identifier, however.
           schema:
             $ref: "definitions/errors/error.yaml"
           examples:
@@ -284,12 +282,12 @@ paths:
             }
         400:
           description: |-
-            The homeserver was unable to location a user with the third party identifier
+            The third party identifier is already in use on the homeserver, or
-            alrady bound, or the request was invalid.
+            the request was invalid.
           schema:
             $ref: "definitions/errors/error.yaml"
           examples:
             application/json: {
-              "errcode": "M_THREEPID_NOT_FOUND",
+              "errcode": "M_THREEPID_IN_USE",
-              "error": "Third party identifier not found"
+              "error": "Third party identifier already in use"
             }

api/client-server/registration.yaml

@@ -406,9 +406,31 @@ paths:
                 required: ['id_server']
       responses:
         200:
-          description: An email was sent to the given address
+          description: An email was sent to the given address.
           schema:
             $ref: "../identity/definitions/sid.yaml"
+        403:
+          description: |-
+            The homeserver does not allow the third party identifier as a
+            contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The referenced third party identifier is not recognised by the
+            homeserver, or the request was invalid
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_NOT_FOUND",
+              "error": "Email not found"
+            }
   "/account/password/msisdn/requestToken":
     post:
       summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
@@ -420,7 +442,7 @@ paths:
         `account/password` endpoint. This API's parameters and response are
         identical to that of the HS API |/register/msisdn/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
+        given phone number could be found. The server may instead send an
         SMS message to the given address prompting the user to create an account.
         `M_THREEPID_IN_USE` may not be returned.
 
@@ -449,6 +471,28 @@ paths:
           description: An SMS message was sent to the given phone number.
           schema:
             $ref: "../identity/definitions/sid.yaml"
+        403:
+          description: |-
+            The homeserver does not allow the third party identifier as a
+            contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The referenced third party identifier is not recognised by the
+            homeserver, or the request was invalid
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_NOT_FOUND",
+              "error": "Phone number not found"
+            }
   "/account/deactivate":
     post:
       summary: "Deactivate a user's account."