Identity

Every join to a Gryt server is a challenge and a signature. The server sends a nonce, the client signs it with a private key that never leaves the device, and the server checks the signature against a certificate that says which key belongs to whom.

That part is the same however somebody joins. What differs is who vouches for the key.

The two kinds of identity

An account is a durable identity. The sub in the certificate is a Keycloak user, so it's the same person on every Gryt server, and losing a device costs nothing — sign in again and the CA certifies a fresh key.

A local identity is a keypair on a device and nothing else. There's no sign-up, no email, and no way for anyone including us to connect it to a person. The client still uses a separate key per server, so two servers can't tell they're talking to the same person — but all of them are worked out from one backup, so there's a single thing to save and it covers servers you join later too.

Choosing what your server accepts

# Accept only Gryt accounts (default)
GRYT_IDENTITY_TIERS=account

# Also accept people with no account
GRYT_IDENTITY_TIERS=account,local

# Only local identities — nobody needs an account, and an account is no help
GRYT_IDENTITY_TIERS=local

Anything unrecognised in the list is ignored, and an empty or unparseable value falls back to account. A server never becomes easier to get into because of a typo.

Clients read this before joining. The Add Server dialog shows "No account needed" or "Gryt account required" as soon as it has fetched the server's /info, so nobody discovers your policy by being turned away.

If bans that stick matter more to you than an easy front door, keep account and lean on invites.

Who gets in

Which identities you accept is a separate question from how hard it's to get in with one. That's the join policy, set in Server settings → Overview → Who can join:

• Invite (default) — everybody who isn't already a member needs an invite code, or a private IP if lan_open is set
• Open — anyone the server accepts can join without an invite

The two settings compose, which is deliberate. "Accounts walk in, guests need an invite" isn't a special case, it is GRYT_IDENTITY_TIERS=account,local with the join policy left at invite — the account holder and the guest both need a code, and neither needs the other's tier.

On an open server the first person to arrive still becomes the owner, exactly as on an invite-only one.

If you're running a server for people in the same room

The desktop app can host a server for you, and it accepts local identities out of the box. Somebody on your network can join from a browser with no account, no sign-up and no round trip to Gryt's servers. Combine it with LAN access in server settings if you would rather not hand out invite codes at a LAN party.

Telling people apart

Nicknames aren't unique on a Gryt server and never have been. Anyone can call themselves anything, which is true whether or not they have an account.

Hovering a member shows what they can't choose:

• when they joined this server
• whether there's an account behind them
• how many times they have renamed themselves, and when they last did
• a fingerprint, stable across renames

The fingerprint is specific to your server. The same person shows a different fingerprint elsewhere, so it can't be used to follow somebody between servers, and it's derived in a way that nobody can grind a key to match. If it matters whether somebody is who they say they are, compare that rather than the name.

Not losing a local identity

A local identity lives in the browser's storage on one device. Clearing site data deletes it, and with it every server that identity was known on — roles, and any server it owns.

Settings → You → Security → Show my identity backup gives you 24 words. That's your identity, on every server you join without an account, including ones you haven't joined yet. Save it in your password manager.

The words are checked when you type them back, so a mistyped or swapped word is rejected rather than quietly making you somebody else. You never have to get them right from memory — copy and paste.

There's no recovery without them. A server owner can move a member to a new identity from Server settings → Replace User, which covers somebody losing a key — but not the owner losing theirs, because nobody is left who can act.

Using the same identity on your phone, or a second computer

No account, and you want to be the same person on another device? Three steps:

1. On the device you already use: Settings → You → Security → Show my identity backup, and copy the 24 words.
2. On the new device: Settings → You → Security → I already have one.
3. Paste the words.

That's it. You're the same member on every server, with the same roles and the same history — and it keeps working for servers you join afterwards, because both devices work out the same keys from the same backup. Nothing needs re-exporting when you join somewhere new.

The field you paste into is a normal password field, so a password manager will offer to save the words the first time and fill them in after that.

Or a file, if you would rather

Save a backup file writes the same thing out as a password-protected file. It's useful if your password manager takes attachments more happily than notes, and it's what the option below reads.

Authorising a device instead of moving your identity to it

On a machine you don't fully control, pasting your words is the wrong move — that device is then permanently you.

Settings → You → Security → Authorise this device takes the backup file and does something different with it. Your key stays in the file. It signs a certificate naming this device's own key, and the server accepts that certificate as you.

• Your key is never written to the second device
• The authorisation expires by itself after 30 days
• Renewing it means picking the file again

Nothing has to be trusted for this to be safe. The identity is derived from the key that did the signing, so a certificate can only ever name the identity of whoever held the file — there's no list of authorised devices to keep, and no decision to get wrong.

Prefer the words on a machine that's yours, and Authorise on one that isn't.

Servers that move

A local identity is tied to the server itself, not to the address it answers on. A server that changes port, or picks up a new address from your router, still knows you — same member, same roles, same history.

One thing that follows from this: a server you can reach two ways, on its LAN address and through a tunnel, is one identity on both. It used to be two.