Merge pull request #2310 from matrix-org/travis/spec/2263-deprecate-i…

…d-server Deprecate id_server and make it optional
matrix-org · Oct 4, 2019 · 3d60e04 · 3d60e04
2 parents 500db6f + 2e84465
commit 3d60e04
Show file tree

Hide file tree

Showing 6 changed files with 29 additions and 6 deletions.
diff --git a/api/client-server/administrative_contact.yaml b/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:

diff --git a/api/client-server/definitions/request_email_validation.yaml b/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.
diff --git a/api/client-server/definitions/request_msisdn_validation.yaml b/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.
diff --git a/api/client-server/registration.yaml b/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:

diff --git a/changelogs/client_server/newsfragments/2310.feature b/changelogs/client_server/newsfragments/2310.feature
@@ -0,0 +1 @@
+Deprecate ``id_server`` and make it optional in several places.
diff --git a/specification/client_server_api.rst b/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:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Deprecate ``id_server`` and make it optional in several places.