BOARDHERALDDocs
// platform.sign_in

Sign-in

Magic links are the default — no passwords to forget, rotate, or phish. A fallback path exists for edge cases. Both go through a deliberate two-step confirmation.

Why magic links

Passwords are the weakest link in most SaaS accounts — reused, phishable, forgotten, leaked. For a surface that contains your company's financials and fundraising plans, that's a poor foundation.

Magic links instead:

  • Are time-bound — 15-minute expiry, one use, consumed on click.
  • Are email-bound — only the person with access to the email inbox can use the link.
  • Don't carry "dictionary attack" risk — no guessable password to try.
  • Don't require remembering anything — members don't manage credentials.

The two-step confirmation

Here's a subtle bug most magic-link systems have: email providers (spam filters, Outlook Safe Links, mailing list gateways, security scanners) often follow every URL in every email to check if it's malicious. Each of those follows is a GET request to your magic link — and if you naively "sign the user in on GET", the scanner consumes the token before the human ever clicks.

BoardHerald splits sign-in into two steps:

  1. The email link is a GET to /auth/confirm?token=…. That page renders a simple "Confirm sign-in" button. It does not create a session on its own.
  2. When the human clicks Confirm, the browser POSTs the token back. Only then does BoardHerald verify the token and issue the session cookie.

Scanners that blindly GET the URL hit the confirmation page but never POST — so they can't consume the token. The human clicks through normally.

Session duration
Sessions last 6 hours by default. On expiry, you get bounced to the sign-in page for a fresh magic link. If you need longer-lived sessions (for a kiosk-style board-room display, say), an ADMIN can configure per-tenant duration in Settings.

Fallback password

Magic links fail in two scenarios:

  • Your email is down (company-wide outage, a board member whose domain got rate-limited).
  • You're in an environment that strips inbound email (an airgapped network, for instance).

For those, BoardHerald has a hidden fallback route at /fallback-login. An ADMIN can enable passwords for specific members in Settings → Members → [member] → Fallback password. The member picks a password (stored as a strong KDF hash server-side), then signs in with email + password instead of magic link.

The fallback password respects the same NDA and role gates as magic-link sessions — you can't bypass anything by using it. All sign-ins (both channels) go through identical audit logging.

Fallback is opt-in per member
Fallback password isn't on by default. An ADMIN has to explicitly enable it for a member — so tenants that want strict magic-link-only enforcement don't accidentally leave a weaker path open.

Platform host vs tenant host

BoardHerald runs on two kinds of hostnames:

  • Platform host — app.boardherald.com. The default sign-in surface. Multi-tenant — your session cookie carries the org you belong to, resolved from the magic link.
  • Tenant host — acme.boardherald.com or your custom domain board.acme.com. Scoped to one specific tenant. Signing in here lands you in that tenant directly; the sign-in page is white-labelled with your branding.

For agents, both hostnames accept MCP traffic on /api/mcp. We recommend pointing agents at the platform host (app.boardherald.com) because the API key itself identifies the tenant — fewer moving parts. See Agents — Configuration.