From a803d9d07753d58137369a72aaab00e9535da9e4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 20:39:53 -0600 Subject: [PATCH 1/6] Document `validated_at` and `added_at` on GET /3pid Fixes https://github.com/matrix-org/matrix-doc/issues/661 --- api/client-server/administrative_contact.yaml | 29 ++++++++++++++----- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 1cf66fe1f6b..1b809c11973 100644 --- 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: From b4be11af4283aad8533f367a0c7a8fc3a98ff1e2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 20:41:34 -0600 Subject: [PATCH 2/6] Document POST /account/3pid/delete Fixes https://github.com/matrix-org/matrix-doc/issues/985 Includes documentation for https://github.com/matrix-org/synapse/pull/3667 Raises https://github.com/matrix-org/matrix-doc/issues/1566 --- api/client-server/administrative_contact.yaml | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 1b809c11973..c1ecf337efc 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -148,6 +148,51 @@ 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. The homeserver + should attempt to unbind the identifier from the identity service, if the + homeserver is able to reasonably determine the identity service used. + 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: + id_server_unbind_result: + type: string + description: |- + The result of the homeserver's attempt to unbind the identifier from + the identity service. ``success`` indicates that the homeserver was + able to unbind the identifier while ``no-support`` means the homeserver + was not able to unbind, likely due to the identity service not supporting + the operation. Defaults to ``no-support``. + example: "success" + 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 From 3b2bf18c67c6953d8f7552a4d88f96f69afe4996 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Sun, 26 Aug 2018 20:54:22 -0600 Subject: [PATCH 3/6] Changelog --- changelogs/client_server/newsfragments/1567.feature | 1 + changelogs/client_server/newsfragments/1567.new | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1567.feature create mode 100644 changelogs/client_server/newsfragments/1567.new diff --git a/changelogs/client_server/newsfragments/1567.feature b/changelogs/client_server/newsfragments/1567.feature new file mode 100644 index 00000000000..0c19b4bea94 --- /dev/null +++ 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 new file mode 100644 index 00000000000..15e3305b1bd --- /dev/null +++ b/changelogs/client_server/newsfragments/1567.new @@ -0,0 +1 @@ +Add ``POST /account/3pid/delete`` From 390f1c16f73b94e47ee100c12fd88de31a7d2a14 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 15:27:36 -0600 Subject: [PATCH 4/6] Remove mentions of identity services from /3pid/delete This will be covered by https://github.com/matrix-org/matrix-doc/issues/1194 For now, we can accept that homeservers may try to unbind, however clients should not rely on it. --- api/client-server/administrative_contact.yaml | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index c1ecf337efc..78e5811b39e 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -152,9 +152,8 @@ paths: post: summary: Deletes a third party identifier from the user's account description: |- - Removes a third party identifier from the user's account. The homeserver - should attempt to unbind the identifier from the identity service, if the - homeserver is able to reasonably determine the identity service used. + Removes a third party identifier from the user's account. This may not + cause an unbind of the identifier from the identity service. operationId: delete3pidFromAccount security: - accessToken: [] @@ -181,16 +180,6 @@ paths: user. schema: type: object - properties: - id_server_unbind_result: - type: string - description: |- - The result of the homeserver's attempt to unbind the identifier from - the identity service. ``success`` indicates that the homeserver was - able to unbind the identifier while ``no-support`` means the homeserver - was not able to unbind, likely due to the identity service not supporting - the operation. Defaults to ``no-support``. - example: "success" tags: - User data "/account/3pid/email/requestToken": From 8bcd7d26e349fd464f88282324411b9eced6d15d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 15:28:43 -0600 Subject: [PATCH 5/6] /3pid/delete returns an empty object --- api/client-server/administrative_contact.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 78e5811b39e..f0362f25b89 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -180,6 +180,7 @@ paths: user. schema: type: object + properties: {} tags: - User data "/account/3pid/email/requestToken": From 5da3072eef94129c0da1a216ef34421415c8f242 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 30 Aug 2018 16:32:14 -0600 Subject: [PATCH 6/6] Wording change ('may not' has a special meaning) --- api/client-server/administrative_contact.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index f0362f25b89..541df43c86e 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -152,7 +152,7 @@ paths: post: summary: Deletes a third party identifier from the user's account description: |- - Removes a third party identifier from the user's account. This may not + 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: