Guests

guests lets people outside the organization in without making them members. You invite a client or contractor by email, they sign in and accept, and they reach only the records you grant them: an invoice, a project, a booking. A guest who acts for a party (a customer company or person) also sees that party's invoices and bookings, which is what a customer portal needs.

better-supabase add guests

import { createGuests } from "better-supabase/blocks/guests";

The module requires tenant and access. With outbox its events are recorded, with audit every invite and grant is audited, and with invoices, bookings and parties a grant can name an invoice, a booking or a party. It renders ahead of comments so the comments, attachments, invoices and bookings policies can let guests in (see ADR 0070).

TablesCopy Anchor Link

A guest is invited, active or revoked. The invite token is stored as a SHA-256 hash and dropped once the guest accepts or is revoked. Members with guests.read see every row; a guest sees their own guest rows and grants.

Invite and acceptCopy Anchor Link

const guests = createGuests({ transport, tenant: organizationId });

const invite = await guests
  .invite({
    email: "jane@client.example",
    name: "Jane",
    party: { type: "customer", id: customerId },
  })
  .orThrow();

await sendInviteEmail(invite.email, `/guest/accept?token=${invite.token}`);

invite returns the guest with a one-time token for the invite link. Inviting the same email again issues a new token, unless the guest has already accepted, in which case token is undefined and only the name and party are updated. expiresAt makes the invite lapse.

The invitee signs in and calls accept(token). Their confirmed email must match the invite, so a forwarded link doesn't let someone else in.

await createGuests({ transport }).accept(token).orThrow();

revoke(guestId) stops every grant and drops the invite token. Inviting the email again restores the guest.

Grant recordsCopy Anchor Link

await guests
  .grant(guest.id, { type: "invoice", id: invoiceId }, { actions: ["comment"] })
  .orThrow();

A grant always includes read; comment and upload add the comments and attachments the guest may write. Granting the same record again replaces the actions and the expiry. The record must exist in the organization: invoices and bookings, and every subject in config.subjects.

The guests section lists a record's guests on its page, with grant and revoke writes.

What guests reachCopy Anchor Link

A guest is never a member: can() stays false for them, and they don't see anything a member query returns. Policies add them through ctx.scope.guest(tenant, type, id, action) and ctx.scope.guestParty(tenant, type, id):

Both checks read the sets better_supabase.portal_subjects(action) and better_supabase.portal_parties(), which Postgres hashes once per statement instead of calling per row. Without the guests block they render false, so a layout without guests keeps its policies as they were.

With an authorization providerCopy Anchor Link

A provider can answer for guests without the block: the optional portalSubjects and portalParties templates in authorization.functions return the records and parties the caller reaches. With the block installed its grants are added to the provider's. See authorization providers.

ErrorsCopy Anchor Link

EventsCopy Anchor Link

guest.invited, guest.accepted and guest.revoked, and guest_grant.created and guest_grant.revoked. The events page lists their payloads.