Skip to content

Invites & joining

Workspaces are private by default. To let a peer in you generate an invite: a small signed payload they paste into their Hive to join.

Invite UI in People pane

Generating an invite

Open the People pane on the right rail. The Workspace Invites section has three controls:

  • Expires in — 1 hour, 1 day, 1 week, or never. Expired invites are rejected on accept.
  • Passcode (optional) — a short string the recipient must also type. Hive never embeds the passcode in the URL — share it on a second channel.
  • Generate — produces both a hive://invite/... URL and a short hyphen-grouped code.

Send the URL or code to your peer through any channel — Signal, email, dictation. The passcode goes separately.

What's in the payload

The invite is a JSON blob, base64url-encoded:

{
  "workspaceID": "uuid",
  "workspaceName": "Hive architecture pass",
  "inviterAccountID": "uuid",
  "inviterDeviceID": "uuid",
  "inviterDisplayName": "Alice",
  "inviterSigningPublicKey": "<base64 32-byte Ed25519>",
  "relayEndpoint": "https://relay.example.com",
  "issuedAt": "2026-05-30T...",
  "expiresAt": "2026-05-30T...",
  "passcode": "rosebud"     // optional
}

The passcode (when present) lives inside the payload, so the URL alone is enough to verify the recipient knows it. Phishing-resistant in the sense that an interceptor with the URL can't accept the invite without also knowing the passcode you communicated separately.

Accepting

In the recipient's Hive:

  1. Open People → Joining a peer's workspace?
  2. Paste the URL or code.
  3. If the inviter set a passcode, paste that too.
  4. Click Accept. Hive verifies signature, expiry, passcode match, then opens the workspace and adds the inviter as a member.

The recipient's device joins the workspace's device roster (a deviceAdded event), at which point envelopes signed by the recipient's device verify on Alice's side too.

Import a roster from a GitHub org (enterprise)

For larger teams, you can seed the workspace roster from a GitHub organization's Teams instead of inviting people one at a time. In the People pane, use the Import GitHub org card:

  1. Sign in with GitHub with the read:org scope (Settings → Account).
  2. Enter the org slug (e.g. acme-inc).
  3. Hive pulls the org's Teams and adds their members to the roster.

Governance roles are mapped from each member's team slug:

Team slug contains Role assigned
admin, owner, lead, maintain Admin
read, viewer, guest, audit Viewer
anything else Contributor

A member who appears on several teams gets the highest role they qualify for. You still control the roster afterward — imported members can be promoted, demoted, or removed like any other.

Nearby on LAN (roadmap)

Zero-config nearby discovery on the same network — synthesizing an invite from a local announcement so peers can join without pasting a link — is a tracked follow-up and not in the current build. See LAN discovery. For now, share an invite link (above) or point both peers at a relay.

Cross-network rendezvous

For peers on different networks, the optional rendezvous relay maps (workspaceID, deviceID) → STUN candidates. Once both peers have published their candidates, the direct P2P link establishes and the relay drops out of the data path.

Set the relay endpoint under Settings → Advanced → Cross-network rendezvous. See Rendezvous relay for the protocol and Self-hosting for how to run one.

Revocation

To kick a peer, remove them as a workspace member (memberRemoved event); their existing envelopes stay in history but new envelopes from their device key get rejected by authz.

For device-level revocation independent of membership, a deviceRevoked event lets an owner blacklist a specific device key even if the user still belongs to the workspace through other devices.