Skip to content

Invite code format

An invite is a single opaque token that carries everything a peer needs to sync a workspace: the relay, the room, and the E2EE key. It is generated by workspaceInvite and redeemed by joinWorkspace (see Invites & joining).

The hivews1: code

The full invite is:

hivews1:<base64url-no-pad(json)>

The body is a WorkspaceConn serialized to JSON and base64url-encoded (- for +, _ for /, no = padding). The JSON carries:

Field Notes
relay_url The relay peers converge on (e.g. wss://relay.example/v1).
room The room id; its hash is the stable workspace id.
key The E2EE passphrase that derives the workspace key. null = a keyless room, which cannot sync through a relay — E2EE is mandatory for relay sync, so a keyless workspace is local-only.
name Friendly display label (defaults to the room name).
dm_account Set only for a 1:1 direct-message workspace; otherwise absent.

The workspace icon is deliberately stripped before encoding — it's local rail decoration and could be a large data: URL.

The code embeds the workspace key

The key field is the actual E2EE passphrase, carried in the clear inside the base64. Anyone who has the code can read the workspace. There is no passcode and no expiry on a raw hivews1: code — treat it like a secret and share it over a channel you trust. For a copy-paste-free alternative, use invite by GitHub handle, which seals the key to the invitee's devices instead of embedding it.

The key is exchanged out-of-band

Because the key field lives inside the hivews1: code, the code is the secret — it is exchanged out-of-band (paste it to the joiner over a channel you trust) and the relay never sees it. There is deliberately no relay-brokered handoff of the key.

The old relay-brokered "short code" — a brief token (e.g. K7P2QX) that published the full hivews1: invite, key and all, to the relay's pairing store — has been removed, precisely because it put the key on the relay. For a copy-paste-free path that keeps the key off the relay, use invite by GitHub handle, which seals the key to the invitee's devices instead of brokering it.

Redemption

joinWorkspace:

  1. Strips the hivews1: prefix and base64url-decodes the body.
  2. Rejects a code whose room is empty or whose encoding is invalid.
  3. Adds the workspace to the rail (refreshing relay/key if the room is already known) and switches to it.

There is no signature check, expiry check, or passcode step on the raw code itself — possession of the code is possession of the key. Authorization for individual envelopes is still enforced workspace-side by the authz evaluator at acceptance time.

See encode_workspace_invite / decode_workspace_invite in app/src/lib.rs for the canonical implementation.