mirror of
https://github.com/element-hq/element-android
synced 2024-11-24 18:35:40 +03:00
314 lines
6.5 KiB
Markdown
314 lines
6.5 KiB
Markdown
# Adding and removing ThreePids to an account
|
|
|
|
<!--- TOC -->
|
|
|
|
* [Add email](#add-email)
|
|
* [User enter the email](#user-enter-the-email)
|
|
* [The email is already added to an account](#the-email-is-already-added-to-an-account)
|
|
* [The email is free](#the-email-is-free)
|
|
* [User receives an e-mail](#user-receives-an-e-mail)
|
|
* [User clicks on the link](#user-clicks-on-the-link)
|
|
* [User returns on Element](#user-returns-on-element)
|
|
* [User enters his password](#user-enters-his-password)
|
|
* [The link has not been clicked](#the-link-has-not-been-clicked)
|
|
* [Wrong password](#wrong-password)
|
|
* [The link has been clicked and the account password is correct](#the-link-has-been-clicked-and-the-account-password-is-correct)
|
|
* [Remove email](#remove-email)
|
|
* [User want to remove an email from his account](#user-want-to-remove-an-email-from-his-account)
|
|
* [Email was not bound to an identity server](#email-was-not-bound-to-an-identity-server)
|
|
* [Email was bound to an identity server](#email-was-bound-to-an-identity-server)
|
|
* [Add phone number](#add-phone-number)
|
|
* [The phone number is already added to an account](#the-phone-number-is-already-added-to-an-account)
|
|
* [The phone number is free](#the-phone-number-is-free)
|
|
* [User receive a text message](#user-receive-a-text-message)
|
|
* [User enter the code to the app](#user-enter-the-code-to-the-app)
|
|
* [Wrong code](#wrong-code)
|
|
* [Correct code](#correct-code)
|
|
* [Remove phone number](#remove-phone-number)
|
|
* [User wants to remove a phone number from his account](#user-wants-to-remove-a-phone-number-from-his-account)
|
|
|
|
<!--- END -->
|
|
|
|
## Add email
|
|
|
|
### 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 added 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 receives 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",
|
|
"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 an 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"
|
|
}
|
|
```
|
|
|
|
## Add phone number
|
|
|
|
> POST https://homeserver.org/_matrix/client/r0/account/3pid/msisdn/requestToken
|
|
|
|
```json
|
|
{
|
|
"country": "FR",
|
|
"phone_number": "611223344",
|
|
"client_secret": "f1K29wFZBEr4RZYatu7xj8nEbXiVpr7J",
|
|
"send_attempt": 1
|
|
}
|
|
```
|
|
|
|
Note that the phone number is sent without `+` and without the country code
|
|
|
|
#### The phone number is already added to an account
|
|
|
|
400
|
|
|
|
```json
|
|
{
|
|
"errcode": "M_THREEPID_IN_USE",
|
|
"error": "MSISDN is already in use"
|
|
}
|
|
```
|
|
|
|
#### The phone number is free
|
|
|
|
Wording: "A text message has been sent to +33611223344. Please enter the verification code it contains."
|
|
|
|
200
|
|
|
|
```json
|
|
{
|
|
"msisdn": "33651547677",
|
|
"intl_fmt": "+33 6 51 54 76 77",
|
|
"success": true,
|
|
"sid": "253299954",
|
|
"submit_url": "https://homeserver.org/_matrix/client/unstable/add_threepid/msisdn/submit_token"
|
|
}
|
|
```
|
|
|
|
## User receive a text message
|
|
|
|
> Riot
|
|
|
|
> Your Riot validation code is 892541, please enter this into the app
|
|
|
|
### User enter the code to the app
|
|
|
|
#### Wrong code
|
|
|
|
> POST https://homeserver.org/_matrix/client/unstable/add_threepid/msisdn/submit_token
|
|
|
|
```json
|
|
{
|
|
"sid": "253299954",
|
|
"client_secret": "f1K29wFZBEr4RZYatu7xj8nEbXiVpr7J",
|
|
"token": "111111"
|
|
}
|
|
```
|
|
|
|
400
|
|
|
|
```json
|
|
{
|
|
"errcode": "M_UNKNOWN",
|
|
"error": "Error contacting the identity server"
|
|
}
|
|
```
|
|
|
|
This is not an ideal, but the client will display a hint to check the entered code to the user.
|
|
|
|
#### Correct code
|
|
|
|
> POST https://homeserver.org/_matrix/client/unstable/add_threepid/msisdn/submit_token
|
|
|
|
```json
|
|
{
|
|
"sid": "253299954",
|
|
"client_secret": "f1K29wFZBEr4RZYatu7xj8nEbXiVpr7J",
|
|
"token": "892541"
|
|
}
|
|
```
|
|
|
|
200
|
|
|
|
```json
|
|
{
|
|
"success": true
|
|
}
|
|
```
|
|
|
|
Then the app call `https://homeserver.org/_matrix/client/r0/account/3pid/add` as per adding an email and follow the same UIS flow
|
|
|
|
## Remove phone number
|
|
|
|
### User wants to remove a phone number from his account
|
|
|
|
This is the same request and response than to remove email, but with this body:
|
|
|
|
```json
|
|
{
|
|
"medium": "msisdn",
|
|
"address": "33611223344"
|
|
}
|
|
```
|
|
|
|
Note that the phone number is provided without `+`, but with the country code.
|