diff --git a/docs/signin.md b/docs/signin.md
new file mode 100644
index 0000000000..d90f00d361
--- /dev/null
+++ b/docs/signin.md
@@ -0,0 +1,118 @@
+# Sign in to a homeserver
+
+This document describes the flow of signin to a homeserver. Examples come from the `matrix.org` homeserver.
+
+## Sign up flows
+
+### First step
+
+Client request the sign-in flows, once the homeserver is chosen by the user and its url is known (in the example it's `https://matrix.org`)
+
+TODO: Complete the doc with signin flow
+
+## Reset password
+
+Ref: `https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-account-password-email-requesttoken`
+
+When the user has forgotten his password, he can reset it by providing an email and a new password.
+
+Here is the flow:
+
+### Send email
+
+User is asked to enter the email linked to his account and a new password.
+We display a warning regarding e2e.
+
+At the first step, we do not send the password, only the email and a client secret, generated by the application
+
+> curl -X POST --data $'{"client_secret":"6c57f284-85e2-421b-8270-fb1795a120a7","send_attempt":0,"email":"user@domain.com"}' 'https://matrix.org/_matrix/client/r0/account/password/email/requestToken'
+
+```json
+{
+  "client_secret": "6c57f284-85e2-421b-8270-fb1795a120a7",
+  "send_attempt": 0,
+  "email": "user@domain.com"
+}
+```
+
+#### When the email is not known
+
+We get a 400
+
+```json
+{
+  "errcode": "M_THREEPID_NOT_FOUND",
+  "error": "Email not found"
+}
+```
+
+#### When the email is known
+
+We get a 200 with a `sid`
+
+```json
+{
+  "sid": "tQNbrREDACTEDldA"
+}
+```
+
+Then the user is asked to click on the link in the email he just received, and to confirm when it's done.
+
+During this step, the new password is sent to the homeserver.
+
+If the user confirms before the link is clicked, we get an error:
+
+> curl -X POST --data $'{"auth":{"type":"m.login.email.identity","threepid_creds":{"client_secret":"6c57f284-85e2-421b-8270-fb1795a120a7","sid":"tQNbrREDACTEDldA"}},"new_password":"weak_password"}' 'https://matrix.org/_matrix/client/r0/account/password'
+
+```json
+{
+  "auth": {
+    "type": "m.login.email.identity",
+    "threepid_creds": {
+      "client_secret": "6c57f284-85e2-421b-8270-fb1795a120a7",
+      "sid": "tQNbrREDACTEDldA"
+    }
+  },
+  "new_password": "weak_password"
+}
+```
+
+401
+
+{
+  "errcode": "M_UNAUTHORIZED",
+  "error": ""
+}
+
+### User clicks on the link
+
+The link has the form:
+
+https://matrix.org/_matrix/client/unstable/password_reset/email/submit_token?token=fzZLBlcqhTKeaFQFSRbsQnQCkzbwtGAD&client_secret=6c57f284-85e2-421b-8270-fb1795a120a7&sid=tQNbrREDACTEDldA
+
+It contains the client secret, a token and the sid
+
+When the user click the link, if validate his ownership and the new password can now be ent by the application (on user demand):
+
+> curl -X POST --data $'{"auth":{"type":"m.login.email.identity","threepid_creds":{"client_secret":"6c57f284-85e2-421b-8270-fb1795a120a7","sid":"tQNbrREDACTEDldA"}},"new_password":"weak_password"}' 'https://matrix.org/_matrix/client/r0/account/password'
+
+```json
+{
+  "auth": {
+    "type": "m.login.email.identity",
+    "threepid_creds": {
+      "client_secret": "6c57f284-85e2-421b-8270-fb1795a120a7",
+      "sid": "tQNbrREDACTEDldA"
+    }
+  },
+  "new_password": "weak_password"
+}
+```
+
+200
+
+```json
+{}
+```
+
+The password has been changed, and all the existing token are invalidated. User can now login with the new password.
\ No newline at end of file