From 66dfcbc2f8052e0df609ba58d4e53f698a7a977e Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Fri, 28 Aug 2020 10:11:38 +0200
Subject: [PATCH] Add documentation on the flows

---
 docs/add_email.md | 177 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 177 insertions(+)
 create mode 100644 docs/add_email.md

diff --git a/docs/add_email.md b/docs/add_email.md
new file mode 100644
index 0000000000..64227418a3
--- /dev/null
+++ b/docs/add_email.md
@@ -0,0 +1,177 @@
+# Adding an email to an account
+
+## User enter the email
+
+> POST https://homeserver.org/_matrix/client/r0/account/3pid/email/requestToken
+
+```json
+{
+  "email": "alice@email-provider.org",
+  "client_secret": "TixzvOnw7nLEUdiQEmkHzkXKrY4HhiGh",
+  "send_attempt": 1
+}
+```
+
+### The email is already adding to an account
+
+400
+
+```json
+{
+  "errcode": "M_THREEPID_IN_USE",
+  "error": "Email is already in use"
+}
+```
+
+### The email is free
+
+Wording: "We've sent you an email to verify your address. Please follow the instructions there and then click the button below."
+
+200
+
+```json
+{
+  "sid": "bxyDHuJKsdkjMlTJ"
+}
+```
+
+## User receive an e-mail
+
+> [homeserver.org] Validate your email
+>
+> A request to add an email address to your Matrix account has been received. If this was you, please click the link below to confirm adding this email:
+  https://homeserver.org/_matrix/client/unstable/add_threepid/email/submit_token?token=WUnEhQAmJrXupdEbXgdWvnVIKaGYZFsU&client_secret=TixzvOnw7nLEUdiQEmkHzkXKrY4HhiGh&sid=bxyDHuJKsdkjMlTJ
+>  
+>  If this was not you, you can safely ignore this email. Thank you.
+
+## User clicks on the link
+
+The browser displays the following message:
+
+> Your email has now been validated, please return to your client. You may now close this window.
+
+## User returns on Element
+
+User clicks on CONTINUE
+
+> POST https://homeserver.org/_matrix/client/r0/account/3pid/add
+
+```json
+{
+  "sid": "bxyDHuJKsdkjMlTJ",
+  "client_secret": "TixzvOnw7nLEUdiQEmkHzkXKrY4HhiGh"
+}
+```
+
+401 User Interactive Authentication
+
+```json
+{
+  "session": "ppvvnozXCQZFaggUBlHJYPjA",
+  "flows": [
+    {
+      "stages": [
+        "m.login.password"
+      ]
+    }
+  ],
+  "params": {
+  }
+}
+```
+
+## User enters his password
+
+POST https://homeserver.org/_matrix/client/r0/account/3pid/add
+
+```json
+{
+  "sid": "bxyDHuJKsdkjMlTJ",
+  "client_secret": "TixzvOnw7nLEUdiQEmkHzkXKrY4HhiGh",
+  "auth": {
+    "session": "ppvvnozXCQZFaggUBlHJYPjA",
+    "type": "m.login.password",
+    "user": "@benoitx:matrix.org",
+    "identifier": {
+      "type": "m.id.user",
+      "user": "@benoitx:matrix.org"
+    },
+    "password": "weak_password"
+  }
+}
+```
+
+### The link has not been clicked
+
+400
+
+```json
+{
+  "errcode": "M_THREEPID_AUTH_FAILED",
+  "error": "No validated 3pid session found"
+}
+```
+
+### Wrong password
+
+401
+
+```json
+{
+  "session": "fXHOvoQsPMhEebVqTnIrzZJN",
+  "flows": [
+    {
+      "stages": [
+        "m.login.password"
+      ]
+    }
+  ],
+  "params": {
+  },
+  "completed":[
+  ],
+  "error": "Invalid password",
+  "errcode": "M_FORBIDDEN"
+}
+```
+
+### The link has been clicked and the account password is correct
+
+200
+
+```json
+{}
+```
+
+# Remove email
+
+## User want to remove the email from his account
+
+> POST https://homeserver.org/_matrix/client/r0/account/3pid/delete
+
+```json
+{
+  "medium": "email",
+  "address": "alice@email-provider.org"
+}
+```
+
+### Email was not bound to an identity server
+
+200
+
+```json
+{
+  "id_server_unbind_result": "no-support"
+}
+```
+
+### Email was bound to an identity server
+
+200
+
+```json
+{
+  "id_server_unbind_result": "success"
+}
+```