Authentication

This kit uses Supabase Auth for every account, including the sessions that approve agent connections and the sessions on the admin app. Nothing on this page is a second login system. For the cross-kit concepts, read the shared authentication page.

Where the configuration lives

Email and password

Sign-up calls supabase.auth.signUp with emailRedirectTo pointing at /auth/callback. Local config.toml sets enable_confirmations = true, so a new user must open the verification email before signing in. The app shows a "check your email" card until then.

Locally, verification emails arrive in Mailpit at the MAILPIT_URL printed by supabase status --output-format json. In production, configure SMTP for the Supabase project. The web app's RESEND_API_KEY does not affect Supabase Auth emails. See emails.

Two routes complete email flows on the web app:

• /auth/callback exchanges a code for a session and then redirects to next or /dashboard.
• /auth/confirm verifies a token_hash for email confirmation or password recovery and redirects to /dashboard or /update-password.

Password reset starts at /forgot-password and finishes at /update-password. config.toml lists exactly four local redirect URLs: /auth/callback and /auth/confirm on http://localhost:3000 (web) and on http://localhost:3002 (admin). The site_url stays on the web origin.

Magic links and social providers

signInWithMagicLinkAction uses signInWithOtp with the same callback. The login page offers it alongside the password form.

Social login is implemented server-side in signInWithProviderAction. The app's provider list is google, github and twitter (apps/web/src/utils/zod-schemas/social-providers.ts), and config.toml enables all three for local Auth with credentials read from GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, TWITTER_API_KEY and TWITTER_API_SECRET.

Sessions and protected routes

apps/web/src/proxy.ts runs the list in middlewares/middleware-list.ts in order for matching paths:

1. authMiddleware on the protected paths from middlewares/paths.ts (/dashboard, /settings, /profile, /workspace, /project, /home, /user, /logout and /onboarding). It calls supabase.auth.getClaims(), refreshes cookies and redirects to /login when there is no session. Claims are parsed with userClaimsSchema so malformed tokens fail loudly.
2. dashboardOnboardingMiddleware and onboardingRedirectMiddleware send users to /onboarding until onboardingHasAcceptedTerms, onboardingHasCompletedProfile and onboardingHasCreatedWorkspace are all set in their user metadata, and back to /dashboard afterwards.

The session is resolved once and passed along the chain. Server components, server actions and route handlers each use a matching client from src/supabase-clients/user/. The service-role client in src/supabase-clients/admin/ is server-only and is never imported into client code. There is no /app-admin route in the web app any more; app-admin is only a reserved slug in apps/web/src/constants.ts.

Becoming an application admin

The admin role is stored in two places that must agree:

• A row in public.user_roles with role = 'admin'. RLS policies and the Admin MCP check this table through is_application_admin() and mcp_live_actor().
• app_metadata.user_role = 'admin' on the Auth user. The admin app's proxy.ts and /app-admin layout read this claim through isSupabaseUserClaimAppAdmin (utils/is-supabase-user-app-admin.ts, present in both apps).

The trusted way to set both is the SQL function make_user_app_admin(user_id uuid) from apps/database/supabase/migrations/20240901054606_application_admin.sql. It can only run as postgres, supabase_admin or dashboard_user, so call it from the Supabase SQL editor or psql, never from the app:

select make_user_app_admin('<your-user-id>');

The user then signs out and back in so the new claim is in their token. remove_app_admin_privilege_for_user(user_id) reverses it. A normal account cannot write app_metadata or user_roles; both are revoked from anon and authenticated.

Locally, seed.sql already calls make_user_app_admin for the seeded admin user testadmin@usenextbase.com. The Playwright admin setup does the same through a direct Postgres connection.

A custom_access_token_hook function also ships in the migrations, but the [auth.hook.custom_access_token] block in config.toml is commented out. The admin claim works without it because make_user_app_admin writes raw_app_meta_data directly.

The admin app

Administration is a separate Next.js app, apps/admin, that deploys on its own origin (port 3002 locally) and shares the Supabase project with the web app. See docs/admin-app.md in the repository.

• /login is an email and password form (signInWithPassword). The admin app has its own /auth/callback and /auth/confirm handlers and a /logout route; / redirects to /app-admin.
• apps/admin/src/proxy.ts runs on /app-admin, /feedback and /roadmap. Without a session it redirects to /login?next=...; with a session whose app_metadata.user_role is not admin it returns 403.
• The /app-admin layout rechecks the claim and calls unauthorized() otherwise. Mutations go through adminActionClient in apps/admin/src/lib/safe-action.ts, which verifies the admin role again before the service-role client is used.
• /app-admin holds users, workspaces, marketing content (blog, changelog, authors, tags), payment gateway data and settings; /feedback and /roadmap on the admin origin are the moderation views.
• Support sign-in and impersonation (apps/admin/src/data/admin/user.tsx) call auth.admin.generateLink and build a link to the web app's /auth/confirm using NEXT_PUBLIC_WEB_APP_URL. The web app verifies the token and sets its own host-scoped cookies; the admin session never leaves the admin origin.

Owning a workspace does not make someone an application admin. See workspaces and the admin area.

What RLS protects

Row Level Security is enabled on every user-facing table defined in apps/database/supabase/migrations/. Policies key off auth.uid(), workspace membership in workspace_members, the workspace_member_role enum (owner, admin, member, readonly) and per-member permissions. Workspace settings are split into a member-visible table and an admin-only table.

apps/database/supabase/tests/ holds pgTap suites for user, workspace, project and marketing tables, function behaviour, security isolation, RLS enforcement and Data API grant safety. Run them with pnpm --filter database test-db while Supabase is running, and add a test whenever you add a table or policy.

The MCP credential table mcp_records is also behind RLS with all browser grants revoked; only service_role can read it. See agent connections.