Merge pull request #1567 from turt2live/travis/c2s/3pid-binding

Document `validated_at`, `added_at`, and POST /3pid/delete
matrix-org · Aug 30, 2018 · ce14779 · ce14779
2 parents 4b7f308 + 5da3072
commit ce14779
Show file tree

Hide file tree

Showing 3 changed files with 59 additions and 7 deletions.
diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml
@@ -47,13 +47,15 @@ paths:
           description: The lookup was successful.
           examples:
             application/json: {
-                "threepids": [
-                  {
-                    "medium": "email",
-                    "address": "monkey@banana.island"
-                  }
-                ]
-              }
+              "threepids": [
+                {
+                  "medium": "email",
+                  "address": "monkey@banana.island",
+                  "validated_at": 1535176800000,
+                  "added_at": 1535336848756
+                }
+              ]
+            }
           schema:
             type: object
             properties:
@@ -70,6 +72,19 @@ paths:
                     address:
                       type: string
                       description: The third party identifier address.
+                    validated_at:
+                      type: integer
+                      format: int64
+                      description: |-
+                        The timestamp, in milliseconds, when the identifier was
+                        validated by the identity service.
+                    added_at:
+                      type: integer
+                      format: int64
+                      description:
+                        The timestamp, in milliseconds, when the homeserver
+                        associated the third party identifier with the user.
+                  required: ['medium', 'address', 'validated_at', 'added_at']
       tags:
         - User data
     post:
@@ -133,6 +148,41 @@ paths:
             "$ref": "definitions/errors/error.yaml"
       tags:
         - User data
+  "/account/3pid/delete":
+    post:
+      summary: Deletes a third party identifier from the user's account
+      description: |-
+        Removes a third party identifier from the user's account. This might not
+        cause an unbind of the identifier from the identity service.
+      operationId: delete3pidFromAccount
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              medium:
+                type: string
+                description: The medium of the third party identifier being removed.
+                enum: ["email", "msisdn"]
+                example: "email"
+              address:
+                type: string
+                description: The third party address being removed.
+                example: "example@domain.com"
+            required: ['medium', 'address']
+      responses:
+        200:
+          description: |-
+            The homeserver has disassociated the third party identifier from the
+            user.
+          schema:
+            type: object
+            properties: {}
+      tags:
+        - User data
   "/account/3pid/email/requestToken":
     post:
       summary: Requests a validation token be sent to the given email address for the purpose of adding an email address to an account

diff --git a/changelogs/client_server/newsfragments/1567.feature b/changelogs/client_server/newsfragments/1567.feature
@@ -0,0 +1 @@
+Document the ``validated_at`` and ``added_at`` fields on ``GET /acount/3pid``.
diff --git a/changelogs/client_server/newsfragments/1567.new b/changelogs/client_server/newsfragments/1567.new
@@ -0,0 +1 @@
+Add ``POST /account/3pid/delete``