Identity and accounts #

Every Matrix identity is a Matrix User ID (MXID) of the form:

@localpart:server-name

For example:

@alice:your-name.hagency.cloud

• @ is the sigil that marks this as a user. Other sigils are ! for rooms, # for room aliases and $ for events (more below).
• localpart — the account name inside one homeserver. Allowed characters per the spec are [a-z0-9._=-] plus / in historical accounts, with length up to 255 chars. Case is usually preserved but compared case-insensitively.
• server-name — the homeserver's DNS name. Two users with the same localpart on different homeservers are completely separate people.

The MXID is permanent. Your display name (a human-friendly label like "Alice Chen") and avatar can change at any time; the MXID cannot. This is important when people verify each other's identities — you verify an MXID, not a display name, because display names are easy to spoof.

Matrix sigils #

Matrix uses four prefix characters to mark what kind of thing an identifier refers to:

Internal room IDs (!…) are opaque and unique forever. A room alias (#general:server) is a human-friendly pointer at a room ID; the same room can have many aliases and they can be changed by room admins.

Third-party identifiers (3PIDs) #

You can also bind "external" identifiers to your Matrix account: email addresses, phone numbers, and (historically) Microsoft/Google accounts. These 3PIDs let someone find you by email or phone even if they don't know your MXID. Binding is stored in an identity server (Hagency runs its own) and is revocable at any time.

How lookup works #

1. Alice wants to invite bob@example.com to a room.
2. Her client asks the identity server: "got a Matrix account bound to this email?"
3. If so, the identity server returns Bob's MXID and the client sends the invite.
4. If not, the client can send an email invite instead — Bob gets a link that, when clicked, creates or signs into a Matrix account and claims the pending invite.

3PID lookup is opt-in: you have to explicitly bind the 3PID to make yourself discoverable. Many Matrix users operate anonymously behind just a localpart and never touch 3PIDs.

Privacy #

Identity servers are a classic privacy trade-off. You gain discoverability but you also publish "this 3PID belongs to a Matrix user" to anyone who looks. Hagency's per-workspace identity server is scoped to your workspace — external servers can't enumerate it. If you don't care about 3PID discovery, don't bind anything.

Device IDs #

When you sign in from a new client — laptop, phone, tablet, server-side bot — the homeserver gives that session a device ID (e.g. WOXXHRVJKP). One MXID can have many device IDs simultaneously, one per place you're signed in.

• Each device has its own access token.
• Each device has its own cryptographic device keys used for end-to-end encryption (covered in Encryption).
• You can list and revoke devices from your client's security settings, or from the Hagency dashboard's Matrix-users panel.
• Logging out on one device revokes that one device. You can also force-logout everything at once ("log out all sessions") if you think something was compromised.

Devices are the unit of E2EE trust: when someone verifies "Alice", what they're really verifying is Alice's cross-signing key, which in turn vouches for all of Alice's devices. New devices get added to the list and need to be re-verified (or they piggyback on cross-signing, which we cover in the encryption section).

Your first Hagency Server account #

Your Hagency Cloud platform account and your Hagency Server account are separate. After creating the server, open its account center at /auth/ and register the first administrator. That account has its own credentials and Matrix ID on the server.

Set a custom Matrix ID domain before creating server users. To manage users and rooms from Hagency Cloud, authorize platform management in the server settings. Additional server users can be created through the management tools or self-registration when enabled.

What's next #

• Encryption — how device keys become the unit of E2EE trust
• Architecture — the homeserver that stores your account
• Clients — pick an app and sign in