Skip to main content

Authentication

NearSync's authentication system is built on Supabase Auth, which provides JWT-based authentication, session management, and multi-factor authentication. This page covers how authentication works at each layer.

JWT Authentication​

All non-public API endpoints require a valid JSON Web Token (JWT) in the Authorization header.

Token Lifecycle​

  1. Issuance - Supabase Auth issues a JWT when a user signs in (email/password, magic link, or OAuth)
  2. Access token - Short-lived (default: 1 hour). Used for API requests.
  3. Refresh token - Longer-lived (default: 7 days). Used to obtain new access tokens without re-authentication.
  4. Validation - Edge Functions validate the JWT server-side by checking the signature and expiry against Supabase Auth
  5. Rejection - Invalid or expired tokens return 401 Unauthorized

Public Endpoints​

A small number of endpoints are whitelisted and do not require authentication:

  • Booking and availability endpoints (public scheduling)
  • Invite validation and acceptance (pre-authentication flow)
  • User creation (signup flow)
  • Document and payment verification (public links)
  • Page view tracking (analytics)

All other endpoints require a valid JWT.

Session Management​

Cross-Domain Sessions​

NearSync runs across multiple subdomains (admin dashboard, client portal, marketing site). Sessions are stored in chunked HTTP cookies scoped to the parent domain, enabling seamless cross-subdomain authentication.

How chunked cookies work:

Supabase Auth sessions can exceed the 4KB cookie size limit. NearSync splits the session into 3,500-byte chunks stored as separate cookies. The Supabase client library reassembles them transparently.

Cookie attributes:

AttributeValueReason
SecureYes (production)Cookies only sent over HTTPS
SameSiteLaxAllows cross-subdomain navigation while protecting against CSRF
DomainParent domainShared across all subdomains

Development fallback: On localhost (where cookies cannot be shared across ports), sessions fall back to localStorage.

Session Expiry​

  • Access tokens expire after 1 hour by default
  • Refresh tokens expire after 7 days by default
  • The Supabase client library handles automatic token refresh in the background
  • If the refresh token expires, the user is redirected to the login page

Multi-Factor Authentication​

NearSync supports TOTP-based (Time-based One-Time Password) multi-factor authentication via Supabase Auth's MFA API.

How It Works​

  1. Enrollment - Users enroll by scanning a QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.)
  2. Verification - On each login, the user provides their TOTP code after entering their password
  3. Recovery - Recovery codes are generated during enrollment for account recovery

Organization-Level Enforcement​

MFA can be required at the organization level via the system manifest's security.mfa_required flag. When enabled, all users in that organization must enroll in MFA before accessing the platform.

Staff Invitations​

New users are onboarded via a token-based invitation system:

  1. An admin creates an invitation in the admin dashboard
  2. A unique invite token is generated server-side with a 7-day expiry
  3. The invite email contains a signup link with the token
  4. When the recipient clicks the link, the token is validated server-side before the signup form is shown
  5. On successful signup, the user is assigned the role specified in the invitation

Security properties:

  • Invite tokens are generated server-side (never client-side)
  • Tokens are single-use and expire after 7 days
  • Token status is tracked in the database (pending, accepted, expired, revoked)
  • Server-side validation prevents token reuse or manipulation

Password Security​

  • Password hashing is managed by Supabase Auth using bcrypt
  • Password complexity requirements are configurable per-project in Supabase settings
  • NearSync application code never handles raw passwords - all password operations are delegated to Supabase Auth