Matrix Account Management

Unsure what an EMS account is, see the 'Understanding Your Element Accounts' page above.

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.

create_account_prompt

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:

  1. Go to Element All settings

    profile_menu

  2. Enter your email address and click Add

    adding_email_address

  3. When you get this message, check your email

    check_email_prompt

  4. Click the link in the email. Make sure it opens in another tab/window, leaving your Element client where it is

    verification_email

  5. When you get this message, you can close the verification tab/window and return to Element

    email_validated

  6. Go back to Element and click Continue

    check_email_prompt

  7. Enter your account password or confirm using SSO, then click Continue

    idenity_confirmation

  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

    email_add_success

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.

  1. Go to Element All settings

    profile_menu

    You might want to export your E2E room keys. Just to be on the safe side in case something goes wrong. See also Export and Import E2E Room Keys

  2. Enter your current password and your new password

    set_new_account_password

  3. Click OK

    password_change_success

  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

{
    "password": "new_password"
}

Recovering a Matrix Account

Disclaimer: 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

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

  1. Sign out of Element

    profile_menu

  2. Click Sign out

    sign_out_prompt

  3. Click "Not sure of your password? Set a new one"

    element_sign_in

  4. Enter your email address, and a new password. Then click Send Reset Email

    set_a_new_password

  5. When you get this message, check your email

    set_a_new_passwor_pending_email

  6. Click the link in the email. Make sure it opens in new browser tab, leaving your Element client open

    verification_email

  7. Click Confirm changing my password

    password_reset_confirmation

  8. You can now close this tab and return to Element

    email_validated

  9. Click I have verified my email address

    set_a_new_passwor_pending_email

  10. Click Return to login screen

    password_reset_success

  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 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:

deactivate_account_warning_and_confirmation_prompt

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
}