Merge pull request #2310 from matrix-org/travis/spec/2263-deprecate-id-server

Deprecate id_server and make it optional

Author: turt2live

api/client-server/administrative_contact.yaml

@@ -343,7 +343,9 @@ paths:
         400:
           description: |-
             The third party identifier is already in use on the homeserver, or
-            the request was invalid.
+            the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
+            can be returned if the server does not trust/support the identity server
+            provided in the request.
           schema:
             $ref: "definitions/errors/error.yaml"
           examples:
@@ -391,7 +393,9 @@ paths:
         400:
           description: |-
             The third party identifier is already in use on the homeserver, or
-            the request was invalid.
+            the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
+            can be returned if the server does not trust/support the identity server
+            provided in the request.
           schema:
             $ref: "definitions/errors/error.yaml"
           examples:

api/client-server/definitions/request_email_validation.yaml

@@ -22,11 +22,15 @@ allOf:
         The hostname of the identity server to communicate with. May optionally
         include a port. This parameter is ignored when the homeserver handles
         3PID verification.
+
+        This parameter is deprected with a plan to be removed in a future specification
+        version for ``/account/password`` and ``/register`` requests.
       example: "id.example.com"
     id_access_token:
       type: string
       description: |-
         An access token previously registered with the identity server. Servers
         can treat this as optional to distinguish between r0.5-compatible clients
         and this specification version.
-  required: ["id_server", "id_access_token"]
+
+        Required if an ``id_server`` is supplied.

api/client-server/definitions/request_msisdn_validation.yaml

@@ -22,11 +22,15 @@ allOf:
         The hostname of the identity server to communicate with. May optionally
         include a port. This parameter is ignored when the homeserver handles
         3PID verification.
+
+        This parameter is deprected with a plan to be removed in a future specification
+        version for ``/account/password`` and ``/register`` requests.
       example: "id.example.com"
     id_access_token:
       type: string
       description: |-
         An access token previously registered with the identity server. Servers
         can treat this as optional to distinguish between r0.5-compatible clients
         and this specification version.
-  required: ["id_server", "id_access_token"]
+
+        Required if an ``id_server`` is supplied.

api/client-server/registration.yaml

@@ -425,7 +425,9 @@ paths:
         400:
           description: |-
             The referenced third party identifier is not recognised by the
-            homeserver, or the request was invalid
+            homeserver, or the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
+            can be returned if the server does not trust/support the identity server
+            provided in the request.
           schema:
             $ref: "definitions/errors/error.yaml"
           examples:
@@ -485,7 +487,9 @@ paths:
         400:
           description: |-
             The referenced third party identifier is not recognised by the
-            homeserver, or the request was invalid
+            homeserver, or the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
+            can be returned if the server does not trust/support the identity server
+            provided in the request.
           schema:
             $ref: "definitions/errors/error.yaml"
           examples:

changelogs/client_server/newsfragments/2310.feature

@@ -0,0 +1 @@
+Deprecate ``id_server`` and make it optional in several places.

specification/client_server_api.rst

@@ -809,6 +809,9 @@ To use this authentication type, clients should submit an auth dict as follows:
     "session": "<session ID>"
   }
 
+Note that ``id_server`` (and therefore ``id_access_token``) is optional if the
+``/requestToken`` request did not include them.
+
 Phone number/MSISDN-based (identity / homeserver)
 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 :Type:
@@ -838,6 +841,9 @@ To use this authentication type, clients should submit an auth dict as follows:
     "session": "<session ID>"
   }
 
+Note that ``id_server`` (and therefore ``id_access_token``) is optional if the
+``/requestToken`` request did not include them.
+
 Dummy Auth
 <<<<<<<<<<
 :Type: