The Supabase service-role key — when to use it, when not to, and how it leaks

What it is

Supabase issues two API keys per project: the `anon` (anonymous) key, intended for use in browser code and gated by RLS policies; and the `service_role` key, which bypasses RLS entirely and has the same database privileges as the postgres superuser. The anon key is meant to ship in your client bundle. The service-role key is meant to live only on the server and never touch any code path reachable from the browser.

Vulnerable example

// lib/supabase.ts — WRONG
import { createClient } from "@supabase/supabase-js";

// Bug: uses service-role key, file is imported by client components.
// The service-role key ships in the client bundle. Game over.
export const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,  // <-- in client bundle
);

Fixed example

// lib/supabase-client.ts — for client components
import { createClient } from "@supabase/supabase-js";
export const supabaseClient = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,  // anon key only
);

// lib/supabase-admin.ts — server-side ONLY
import "server-only";  // <-- throws if imported by client
import { createClient } from "@supabase/supabase-js";

// Service-role client for admin operations that legitimately need
// to bypass RLS (e.g. webhook handlers, scheduled jobs, internal
// admin actions). Never imported by client components.
export const supabaseAdmin = createClient(
  process.env.SUPABASE_URL!,                     // no NEXT_PUBLIC_ prefix
  process.env.SUPABASE_SERVICE_ROLE_KEY!,
  { auth: { autoRefreshToken: false, persistSession: false } },
);

How Securie catches it

// lib/supabase-client.ts — for client components
import { createClient } from "@supabase/supabase-js";
export const supabaseClient = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,  // anon key only
);

// lib/supabase-admin.ts — server-side ONLY
import "server-only";  // <-- throws if imported by client
import { createClient } from "@supabase/supabase-js";

// Service-role client for admin operations that legitimately need
// to bypass RLS (e.g. webhook handlers, scheduled jobs, internal
// admin actions). Never imported by client components.
export const supabaseAdmin = createClient(
  process.env.SUPABASE_URL!,                     // no NEXT_PUBLIC_ prefix
  process.env.SUPABASE_SERVICE_ROLE_KEY!,
  { auth: { autoRefreshToken: false, persistSession: false } },
);

Checklist

• Anon key is the ONLY Supabase key in any file that runs in the browser.
• Service-role key is wrapped behind `import "server-only"` to enforce server-only import at compile time.
• Service-role key environment variable does NOT have the `NEXT_PUBLIC_` prefix.
• Service-role key is never logged, never put in URL params, never sent in error messages.
• Service-role key is rotated immediately if it ever appears in a commit, even briefly (history rewrites do not help — once public, the key is in scrapers' pools).
• Server-side code that uses service-role still validates the request before performing privileged operations — service-role is the database key, not an authorization grant.
• Webhook handlers that use service-role verify the webhook signature first.

FAQ

Related guides