Share links

A share link is a URL that, when visited, sets a cookie in the visitor's browser. The cookie satisfies the share-link gate (see Grants and visibility) for that browser, for as long as the share link is active.

Use share links when you want to give someone access without making them sign up — clients reviewing previews, designers sanity-checking mockups, journalists embargo-previewing a launch.

Create

vibehost app share-link create --app my-site

Output:

{
  "ok": true,
  "data": {
    "id": "shr_abc123",
    "url": "https://my-site.vibehost.space/_share/vhs_abc123def",
    "label": null,
    "createdAt": "2026-05-23T08:00:00Z",
    "expiresAt": null,
    "revokedAt": null
  }
}

Send data.url to the recipient. The first time they open it, their browser gets a signed 24-hour cookie (vh_app_share_<appId>) that satisfies the share-link gate (visibility/grant) on subsequent requests. If the app has a password set, the visitor will still be prompted for it — the password gate is separate and always applies.

Options:

vibehost app share-link create --app my-site \
  --label "Acme review — Q2 pitch" \
  --expires 14d

• --label — searchable note. Shows up in share-link ls and in the dashboard. Pick something you'll recognize in 6 months.
• --expires — duration (24h, 7d, 14d, 30d) OR ISO timestamp. After expiry the link returns 410.

List + revoke

Plain ls shows the active links; --include-revoked adds revoked + expired ones; --json is for filtering with jq.

vibehost app share-link ls --app my-site
vibehost app share-link ls --app my-site --include-revoked
vibehost app share-link ls --app my-site --json

Revoke by full ID or unique prefix (the second form below is a prefix match):

vibehost app share-link revoke shr_abc123def --app my-site
vibehost app share-link revoke vhs_abc --app my-site

Revocation is immediate — the cookie persists in the visitor's browser but the dispatcher rejects it on next request.

Three scenarios

vibehost app visibility client-pitch private
vibehost app share-link create --app client-pitch \
  --label "Acme Q2 review" \
  --expires 14d

vibehost app share-link create --app client-pitch \
  --label "Acme Q2 review — extension" \
  --expires 14d

vibehost app grants add-email reviewer@partner.com viewer --app new-feature

vibehost app visibility new-feature private
vibehost app share-link create --app new-feature \
  --label "Internal review – security team" \
  --expires 7d

vibehost app visibility upcoming-launch private
vibehost app share-link create --app upcoming-launch \
  --label "NYT embargo" \
  --expires 48h
vibehost app share-link create --app upcoming-launch \
  --label "TechCrunch embargo" \
  --expires 48h

vibehost app visibility upcoming-launch public
vibehost app share-link ls --app upcoming-launch --json | \
  jq -r '.data[] | .id' | \
  xargs -I{} vibehost app share-link revoke {} --app upcoming-launch

How it works on the wire

1. Visitor clicks https://my-site.vibehost.space/_share/vhs_abc123def.
2. Dispatcher validates the token (shr_abc123 → not revoked, not expired), sets a signed 24-hour cookie:

   Set-Cookie: vh_app_share_<appId>=<HMAC-signed-payload>;
               Path=/; Max-Age=86400; Secure; HttpOnly; SameSite=Lax

3. Dispatcher 302-redirects to the actual URL.
4. The follow-up request carries the share cookie. The share-link gate sees it and satisfies visibility/grant for this browser — those checks are skipped on every subsequent request as long as the cookie is valid and the share row is still active. The server then runs the password gate: if the app has a password set and there's no valid password cookie, the visitor gets a 401 password prompt. After they enter the password, the server sets a second cookie (vh_app_pw_<appId>, 7-day TTL).
5. With both cookies in place, all subsequent requests in this browser pass: share cookie covers visibility/grant (24 hours); password cookie covers the password gate (7 days). The asymmetric TTLs are deliberate — share cookies belong to outside parties and stay narrow; password cookies belong to viewers re-entering an app they're actively using. Either expiring first just re-prompts that one factor.

The cookie is bound to one app (different apps issue different cookies). One share link can't unlock other apps in the same workspace.

Best practices

What share links don't do

• They don't authenticate the visitor. The cookie is bound to the share link, not the person. Anyone with the URL can satisfy the gate.
• They don't bypass the password gate. A valid share-link cookie satisfies the share-link gate (visibility/grant are skipped) for the app it was minted on — including visibility: private apps with no grants. But if the app has a password set, the visitor still has to enter it; the password cookie is separate and always required. This is by design: minting a share link IS the operator's explicit consent for "anyone with this URL can view (no sign-in required)", but it doesn't override an explicitly set password. If "anyone with this URL, no further friction" is what you want, don't set a password. If "anyone with this URL and this password" is what you want, set both.
• They don't expire by default. Set --expires or revoke manually.
• They don't carry an audit trail of the recipient. If you need "person X opened this on date Y", invite them with a grant instead.

Common errors