Matrix Account Management
Unsure what an EMS account is, see the 'Understanding Your Element Accounts' page above.
- Creating a Matrix Account
- Securing a Matrix Account
- Changing a Matrix Account password
- Recovering a Matrix Account
- Deactivating a Matrix Account
- Reactivating a Matrix Account
Creating a Matrix Account
Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
Creating your Matrix Account
Depending on your homeserver, and it's configuration, the sign-up process may differ slightly, however the overall process should largely follow these steps.
From your Matrix Client, click Create Account
, then make sure to change the homeserver as needed. You can do this by clicking Edit
next to the current homeserver name. Once a homeserver is selected, the client will then show you the available registration / authentication methods.
External Services
External service registration allows you to register for your account using a handful of different login providers, For example, matrix.org allows sign-up using a number of external services, including GitHub.
If you choose to register using an external service, you will not be able to use it with any other account, including if you deactivate the account it is associated with.
Username, Password and Email
For the initial stage of the registration flow, you will need to choose a username, otherwise known as your Matrix ID (MXID). Like email it follows a standardized format, @username:homeserver.com
, for example a username of example-name
on the matrix.org
homeserver would be @example-name:matrix.org
.
Choose carefully, it isn't possible to change your MXID, you will however have a display name, that is freely changeable.
You will also be able to provide an email, this is an optional field, if you add an email you will be able to reset your password. Additionally, adding an email allows you to opt-in to be discoverable by existing contacts.
Privacy Policy
Before your account can be created, you may need to review and accept any policies of the homeserver you wish to join. Do so by clicking the Privacy Policy
link and reading through the document - if you accept the policy, confirm by clicking the checkbox and clicking Accept
.
Creating a Matrix Account on your Homeserver
If you're an EMS customer, you can create your users via the Server Admin tab of the EMS Control Panel.
Alternatively you can make use of the Synapse Admin API to create a Matrix Account on a homeserver you hold an Admin account on. To do so, you will need to use Create or Modify Account from the User Admin API.
https://HOMESERVER_URL/_synapse/admin/v2/users/FULL_USERNAME
{
"password": "user_password",
"displayname": "User",
"threepids": [
{
"medium": "email",
"address": "<user_mail_1>"
},
{
"medium": "email",
"address": "<user_mail_2>"
}
],
"external_ids": [
{
"auth_provider": "<provider1>",
"external_id": "<user_id_provider_1>"
},
{
"auth_provider": "<provider2>",
"external_id": "<user_id_provider_2>"
}
],
"avatar_url": "<avatar_url>",
"admin": false,
"deactivated": false
}
Securing a Matrix Account
Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
Once you have an account, it's important to understand the mechanisms it uses to keep your messages secure. Matrix uses encryption to protect your communication. The keys for this encryption should be kept secure, this is done using Secure Backup.
Secure Backup
After sending your first encrypted message, you'll receive a prompt to Set up Secure Backup
, to safeguard against losing access to encrypted messages & data. If you choose not to, any new sessions you start by logging into different clients, will not be able to see you messages.
If you do not receive a prompt, or chose to action later, you can initiate its setup by clicking on your avatar in the top left, then selecting Security & Privacy
. Under the Encryption
/ Secure Backup
section, select Set up
.
Follow the prompt to set up your Secure Backup, you can opt to use a phrase or always use a Security Key. If you opt for a Security Phrase, you will be able to provide a phrase of your choosing which you will need to provide to any client when you login with your account. Alternatively, if you forget your phrase, or did not provide one - you will need to provide the generated key.
Verified Session
A verified session is a device (any client logged into your account) that has been verified as legitimate. On your accounts' first login, the session will be marked as verified, make sure to set up a Secure Backup, you will need it if you ever lose access to all verified sessions.
When you login to a new session, you will be presented with the option to either provide your Security Key / Phrase, or to request verification from another already verified session. Successfully completing either option will mark your new session as verified.
Forgotten or lost all recovery methods?
If you have forgotten or lost all methods of verifying your account, you will need to Reset
you account. Doing so will result in losing access to all your encrypted messages, and mark all sessions as unverified (treating this new session like your first).
Add Email to your account
Adding an email to your account will allow you to be able to reset your password should you lose it. Simply follow these steps:
-
Click the link in the email. Make sure it opens in another tab/window, leaving your Element client where it is
-
When you get this message, you can close the verification tab/window and return to Element
-
Enter your account password or confirm using SSO, then click
Continue
-
If all worked correctly, your new email should now show up under the
Email addresses
section in Element settings. If not, something went wrong and you need to try again
Securing a Matrix Account on your Homeserver
If you're an EMS customer, you can create your users via the Server Admin tab of the EMS Control Panel.
Alternatively you can make use of the Synapse Admin API to create a Matrix Account on a homeserver you hold an Admin account on. To do so, you will need to use Create or Modify Account from the User Admin API.
https://HOMESERVER_URL/_synapse/admin/v2/users/FULL_USERNAME
{
"threepids": [
{
"medium": "email",
"address": "<user_mail_1>"
},
{
"medium": "email",
"address": "<user_mail_2>"
}
],
}
Changing a Matrix Account password
Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
Changing your Matrix Account password
If you don't know your password, you'll need to recover your account, see our Recovering a Matrix Account page for instructions.
-
Go to Element
All settings
[
- You have your correct key backup passphrase available
Recovering your Matrix Account
This will only work if you have an email address attached to your Matrix account. If you do not have an email address attached, contact the administrators of your homeserver.
Reminder: support@matrix.org does not reset passwords under any circumstances
-
Enter your email address, and a new password. Then click
Send Reset Email
-
Click the link in the email. Make sure it opens in new browser tab, leaving your Element client open
-
Sign in like normal with your new password. Note that all your other sessions have been signed out and you need to sign in again.
Recovering a Matrix Account on your Homeserver
If you're an EMS customer, you can create your users via the Server Admin tab of the EMS Control Panel.
Alternatively you can make use of the Synapse Admin API to manage a Matrix Account on a homeserver you hold an Admin account on. To do so, you will need to use the User Admin API.
Deactivating a Matrix Account
Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
Deactivating your Matrix Account
If you wish to deactivate your account, you can do so by following the below steps:
- Log in to your Matrix Client
- Click on your Avatar / Username in the top left corner
- Open
Settings
- From the bottom of the
General
tab, clickDeactivate
- Check any additional options, if applicable, then enter your password or confirm via SSO to deactivate your account
Please note once the account has been deactivated, it is impossible to reactivate it again or reuse the username. Your user is stored indefinitely to avoid account recycling, as such you may also wish to remove any Third-Party ID's from your account before deactivation, as this may cause issues if you ever attempt to create a new account.
Erasing your Matrix Account
You can also GDPR erase your account, this means messages sent by the user will still be visible by anyone that was in the room when these messages were sent, but hidden from users joining the room afterwards. You can do this by checking the Hide my messages from new joiners
checkbox on the Deactivate Account
confirmation prompt.
Deactivating a Matrix Account on your Homeserver
If you're an EMS customer, you can create your users via the Server Admin tab of the EMS Control Panel.
Alternatively you can make use of the Synapse Admin API to deactivate a Matrix Account on a homeserver you hold an Admin account on. To do so, you will need to use Deactivate Account from the User Admin API.
https://HOMESERVER_URL/_synapse/admin/v1/deactivate/FULL_USERNAME
{
"erase": true
}
Reactivating a Matrix Account
Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
Reactivating your Matrix Account
Matrix.org
Once your account has been deactivated, it is impossible to reactivate it again or reuse the username. Your user is stored indefinitely to avoid account recycling. To protect the security and privacy of our users, we never reactivate, or release deleted usernames. Instead, we recommend creating a new account using a different Matrix ID.
Reactivating a Matrix Account on your Homeserver
If you're an EMS customer, see this FAQ entry.
Alternatively you can make use of the Synapse Admin API to reactivate a Matrix Account on a homeserver you hold an Admin account on. To do so, you will need to use Create or Modify Account from the User Admin API, passing "deactivated": false
as well as providing a new password.
https://HOMESERVER_URL/_synapse/admin/v2/users/FULL_USERNAME
{
"password": "new_password"
"deactivated": false
}