Guest Token

The signed credential that lets a Guest accept or refuse a commitment without logging in.

Definition

A Guest Token is a one-time, time-bounded credential embedded in the public Handshake link (/handshake/{token}). It is HMAC-signed and recorded (hashed) in guest_tokens so the system can verify signature, expiry, recipient email, and single-use without trusting the client.

Avoid: magic link (too generic), invite token (org invites are a different path).

Role

The token is the only credential on the Guest surface — no session, no org membership. The signed payload carries shrubbery id and expiry; the recipient email lives only in the database row so addresses with dots never break the token format. Validation runs both when rendering the page and again inside accept/refuse actions.

TTL is seven days from mint. After accept or refuse, used_at is set and the link will not mutate the row again.

Lifecycle

• Minted — when the Lead sends a Shrubbery to an unknown email (generateGuestToken); raw token goes in the invite email.
• Valid — signature ok, not expired, used_at null, shrubbery still Pending_Handshake.
• Invalid — bad signature, unknown hash, or shrubbery id mismatch.
• Expired — past the seven-day window (payload or row expires_at).
• Used — Guest already responded, or the row left Pending_Handshake by another path.

Related guides

• Guest Handshake Flow

Last updated: 24 July 2026