# Next.js boilerplate with Supabase Auth

> Cookie-based Supabase Auth for the Next.js App Router: sign-in with Google, GitHub and Microsoft buttons for whichever providers your Supabase project has switched on, email and password, magic links, password reset, and profile and security settings. It ships @supabase/ssr clients, session refresh in the proxy and RLS-aware query helpers, and the shared getSessionUser, requireUser and requireRole surface is backed by app_metadata.role.

Postgres-native auth where the database, not the API layer, is the last line of defence.

- **Category:** Sign in
- **Pricing:** Free: 50,000 monthly active users. Pro: 100,000 included, then $0.00325 per MAU. Anonymous sign-ins are included. SAML SSO needs Pro: 50 SSO users included, then $0.015 each.
- **Best for:** Teams already on Supabase Postgres who want row-level security as the authorization model. With the policies right, a buggy query cannot return another tenant's rows.
- **Requires:** supabase
- **Conflicts with:** neon, better-auth, clerk
- **Vendor docs:** https://supabase.com/docs/guides/auth

## Trade-offs

- Authorization lives in SQL policies, not in TypeScript. That is the whole point, and it is also the learning curve: you debug permissions with `explain` and `set role`, not a debugger.
- Auth is coupled to the Supabase project. Moving the database off Supabase means moving users, JWT signing and every policy at the same time.
- Cookie-based sessions in the App Router need a proxy refresh. Skip it and users get logged out after an hour with no error anywhere.
- Roles live in `app_metadata`, which only the service-role key can write. Good for security, awkward for self-service role changes.
- The service-role key bypasses every policy. One import of it into a client component and the whole database is public.

## Known fixes it ships

- [Logged out after an hour: Supabase cookie refresh in the App Router](https://agenticboilerplate.com/cookbook/supabase-auth/cookie-refresh-in-the-app-router): Access tokens expire hourly and Server Components cannot write cookies, so the refresh has to happen in the proxy and be returned on the same response object.
- [getSession() vs getUser(): the Supabase trust trap](https://agenticboilerplate.com/cookbook/supabase-auth/getsession-vs-getuser): getSession() decodes a cookie the browser controls; getUser() verifies it with the auth server. On the server, only one of them is a security check.
- [Admin impersonation on Supabase Auth, bound to one session](https://agenticboilerplate.com/cookbook/supabase-auth/impersonation-bound-to-one-session): Supabase Auth has no "view as user". Build it from a server-side magic link plus an app_metadata marker tied to the new session id, so only that session is flagged and nobody can forge it.
- [Migrating an app that only ever used the anon key](https://agenticboilerplate.com/cookbook/supabase-auth/migrating-from-anon-key-only-access): Tables with RLS off are public. Turn it on table by table behind a feature switch, write the policies, and fix the queries the policies break, in that order.
- [Show only the OAuth buttons your Supabase project has switched on](https://agenticboilerplate.com/cookbook/supabase-auth/oauth-buttons-from-auth-settings): Read the public /auth/v1/settings endpoint on the server, cache it, and fail closed, so a sign-in page never shows a Google button that ends on an error page.
- [RLS policy patterns for multi-tenant rows](https://agenticboilerplate.com/cookbook/supabase-auth/rls-patterns-for-multi-tenant-rows): Owner-scoped, org-scoped and role-scoped policies, the with-check clause people forget, and the indexes that stop a policy from turning every read into a scan.
- [The blast radius of a leaked Supabase service-role key](https://agenticboilerplate.com/cookbook/supabase-auth/service-role-key-blast-radius): The key bypasses every policy for every table. Here is how it leaks, what an attacker gets, how to contain it, and how to make the leak impossible.

## Generate it

[Build a repo with Supabase Auth](https://agenticboilerplate.com/build?b=supabase-auth)

---

Agentic Boilerplate: A Next.js repo your agent already knows. Free during launch, then $99 once.

- Site map for agents: https://agenticboilerplate.com/llms.txt
- Public API: https://agenticboilerplate.com/openapi.json
- Contact: agenticstudio@gmail.com