Litter the client-server API with id_access_token

api/client-server/administrative_contact.yaml

@@ -110,10 +110,13 @@ paths:
                   id_server:
                     type: string
                     description: The identity server to use.
+                  id_access_token:
+                    type: string
+                    description: An access token previously registered with the identity server.
                   sid:
                     type: string
                     description: The session identifier given by the identity server.
-                required: ["client_secret", "id_server", "sid"]
+                required: ["client_secret", "id_server", "id_access_token", "sid"]
               bind:
                 type: boolean
                 description: |-
@@ -125,6 +128,7 @@ paths:
             example: {
                 "three_pid_creds": {
                   "id_server": "matrix.org",
+                  "id_access_token": "abc123_OpaqueString",
                   "sid": "abc123987",
                   "client_secret": "d0n'tT3ll"
                 },
@@ -189,6 +193,11 @@ paths:
                     homeserver does not know the original ``id_server``, it MUST return
                     a ``id_server_unbind_result`` of ``no-support``.
                 example: "example.org"
+              id_access_token:
+                type: string
+                description: |-
+                  An access token previously registered with the identity server. Required
+                  if an ``id_server`` is specified.
               medium:
                 type: string
                 description: The medium of the third party identifier being removed.

api/client-server/create_room.yaml

@@ -139,6 +139,9 @@ paths:
                     id_server:
                       type: string
                       description: The hostname+port of the identity server which should be used for third party identifier lookups.
+                    id_access_token:
+                      type: string
+                      description: An access token previously registered with the identity server.
                     medium:
                       type: string
                       # TODO: Link to Identity Service spec when it eixsts
@@ -146,7 +149,7 @@ paths:
                     address:
                       type: string
                       description: The invitee's third party identifier.
-                  required: ["id_server", "medium", "address"]
+                  required: ["id_server", "id_access_token", "medium", "address"]
               room_version:
                 type: string
                 description: |-

api/client-server/definitions/request_email_validation.yaml

@@ -23,4 +23,7 @@ allOf:
         include a port. This parameter is ignored when the homeserver handles
         3PID verification.
       example: "id.example.com"
-  required: ["id_server"]
+    id_access_token:
+      type: string
+      description: An access token previously registered with the identity server.
+  required: ["id_server", "id_access_token"]

api/client-server/definitions/request_msisdn_validation.yaml

@@ -23,4 +23,7 @@ allOf:
         include a port. This parameter is ignored when the homeserver handles
         3PID verification.
       example: "id.example.com"
-  required: ["id_server"]
+    id_access_token:
+      type: string
+      description: An access token previously registered with the identity server.
+  required: ["id_server", "id_access_token"]

api/client-server/registration.yaml

@@ -542,6 +542,11 @@ paths:
                   it must return an ``id_server_unbind_result`` of
                   ``no-support``.
                 example: "example.org"
+              id_access_token:
+                type: string
+                description: |-
+                  An access token previously registered with the identity server. Required if an
+                  ``id_server`` is supplied.
       responses:
         200:
           description: The account has been deactivated.

api/client-server/third_party_membership.yaml

@@ -92,6 +92,7 @@ paths:
             type: object
             example: {
                 "id_server": "matrix.org",
+                "id_access_token": "abc123_OpaqueString",
                 "medium": "email",
                 "address": "cheeky@monkey.com"
               }
@@ -99,6 +100,9 @@ paths:
               id_server:
                 type: string
                 description: The hostname+port of the identity server which should be used for third party identifier lookups.
+              id_access_token:
+                type: string
+                description: An access token previously registered with the identity server.
               medium:
                 type: string
                 # TODO: Link to Identity Service spec when it eixsts
@@ -106,7 +110,7 @@ paths:
               address:
                 type: string
                 description: The invitee's third party identifier.
-            required: ["id_server", "medium", "address"]
+            required: ["id_server", "id_access_token", "medium", "address"]
       responses:
         200:
           description: The user has been invited to join the room.

specification/client_server_api.rst

@@ -802,7 +802,8 @@ To use this authentication type, clients should submit an auth dict as follows:
       {
         "sid": "<identity server session id>",
         "client_secret": "<identity server client secret>",
-        "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>"
+        "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>",
+        "id_access_token": "<access token previously registered with the identity server>"
       }
     ],
     "session": "<session ID>"
@@ -830,7 +831,8 @@ To use this authentication type, clients should submit an auth dict as follows:
       {
         "sid": "<identity server session id>",
         "client_secret": "<identity server client secret>",
-        "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>"
+        "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>",
+        "id_access_token": "<access token previously registered with the identity server>"
       }
     ],
     "session": "<session ID>"