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. [](https://ems-docs.element.io/uploads/images/gallery/2023-06/image-1686041959863.png) #### 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 ``` ```json { "password": "user_password", "displayname": "User", "threepids": [ { "medium": "email", "address": "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: 1. Go to Element `All settings` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651101546-24-15-pm.png) 2. Enter your email address and click `Add` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651182568-51-19-am.png) 3. When you get this message, check your email [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651265482-57-57-am.png) 4. Click the link in the email. Make sure it opens in another tab/window, leaving your Element client where it is [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651210107-55-01-am.png) 5. When you get this message, you can close the verification tab/window and return to Element [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651288348-00-03-pm.png) 6. Go back to Element and click `Continue` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651323286-57-57-am.png) 7. Enter your account password or confirm using SSO, then click `Continue` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651357335-01-34-pm.png) 8. 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 [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651385753-02-17-pm.png) ### 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 ``` ```json { "threepids": [ { "medium": "email", "address": "Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Changing your Matrix Account passwordIf you don't know your password, you'll need to recover your account, see our Recovering a Matrix Account page for instructions.
1. Go to Element `All settings` [ 2. Enter your current password and your new password [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651780042-26-13-pm.png) 3. Click `OK` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651805137-31-01-pm.png) 4. You now need to sign in again on all your other devices ### Changing a Matrix Account password 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 change a Matrix Account password 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 ``` ```json { "password": "new_password" } ``` # Recovering a Matrix AccountDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
Resetting the account password will log out all your sessions, before doing this, make sure that - All your sessions are connected to Secure Backup - All sessions have backed up all their keys ([Check Cross Signing Status](https://ems-docs.element.io/books/element-cloud-documentation/page/check-status)) - You have your correct key backup passphrase available ### Recovering your Matrix AccountThis 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
1. Sign out of Element [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651991898-32-36-pm.png) 2. Click `Sign out` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652013530-15-05-pm.png) 3. Click "Not sure of your password? `Set a new one`" [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652041660-15-56-pm.png) 4. Enter your email address, and a new password. Then click `Send Reset Email` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652072517-20-13-pm.png) 5. When you get this message, check your email [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652099747-22-21-pm.png) 6. Click the link in the email. Make sure it opens in new browser tab, leaving your Element client open [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652128382-23-42-pm.png) 7. Click `Confirm changing my password` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652188389-26-36-pm.png) 8. You can now close this tab and return to Element [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652219082-27-21-pm.png) 9. Click `I have verified my email address` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652254888-22-21-pm.png) 10. Click `Return to login screen` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652295124-28-38-pm.png) 11. 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 AccountDisclaimer: 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, click `Deactivate` - Check any additional options, if applicable, then enter your password or confirm via SSO to deactivate your account [](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1679492386786.png) 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 ``` ```json { "erase": true } ``` # Reactivating a Matrix AccountDisclaimer: 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](https://ems-docs.element.io/link/6#bkmrk-how-do-i-reactivate-). 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 ``` ```json { "password": "new_password" "deactivated": false } ```