Supabase service role key: setup and safe use

SUPABASE_SERVICE_ROLE_KEY usually names an environment variable holding Supabase’s legacy privileged API key. Keep it on the backend. For new integrations, Supabase recommends its newer sb_secret_... keys. Both provide privileged data access; changing the key format does not make it suitable for frontend code. See the official API-key guide.

Where do I find the service-role key?

Open the intended project in the Supabase Dashboard, then Settings → API Keys. Check the legacy keys if an existing integration specifically requires service_role. For a new backend integration, use a secret key supported by that integration instead. Verify the project URL before copying anything.

The variable name alone does not determine permissions. A variable called SUPABASE_SERVICE_ROLE_KEY may contain the wrong value; renaming a secret to include PUBLIC does not reduce its privileges.

Which key belongs where?

Supabase documents the new and legacy types in its API-key reference. API keys identify the application component; user authentication is separate.

Configure a backend without exposing the credential

Use your hosting provider’s server-side secret store. Keep the value out of source control, client configuration, screenshots, and logs. Review both where the variable is defined and where the code that reads it runs.

Before deploying, trace the call:

1. Which server route or background job needs elevated access?
2. What verifies the caller’s identity?
3. What checks whether that caller may perform the requested operation?
4. Can a caller change an account ID or record ID to affect another user?
5. Does the response expose more data than the operation requires?

For ordinary user requests, prefer a user-scoped client and policies that express the user’s allowed access. Reserve a privileged client for operations that actually need it. A backend proxy with no authorization check merely moves the exposure behind another URL.

Does the service role bypass RLS?

Yes, when the request runs as service_role. However, database grants and RLS are separate controls. Grants determine whether a role can access an object; RLS determines which rows are allowed. Bypassing row policies does not mean every permission error is impossible. See Supabase’s Data API security guide.

When testing user isolation, use ordinary test users. A successful privileged query does not verify that your RLS policies protect one user’s records from another.

Why does my service-role client still get an RLS error?

Supabase’s service-role troubleshooting guide explains that the effective Authorization header matters. A user session can replace the client’s privileged authorization, including through SSR cookies, a manually supplied user token, or an Auth operation that establishes a session.

Check whether the operation should run as the user or as a backend administrator. Keep the user-session client separate from the privileged client. Do not remove user authorization simply to silence an error in a user-scoped operation.

Then verify the project, schema, table grants, and filters. An empty result needs a different investigation from a permission error.

What if the key has already leaked?

Treat a privileged credential in a public bundle, repository, or shared log as an exposure. Stop distributing it and investigate its use. Replacing the value in your environment does not invalidate copies already obtained by someone else.

Plan replacement and revocation using the current Supabase key lifecycle instructions. Inventory the services that depend on the credential so that containment and recovery account for them. Inspect the replacement deployment before declaring the incident resolved.

The service-role exposure walkthrough covers the frontend leak scenario. For the broader configuration, use the Supabase hardening guide and RLS guide.

Documentation reviewed October 8, 2026.