Understanding API keys

Supabase gives you fine-grained control over which application components are allowed to access your project through API keys.

API keys provide the first layer of authentication for data access. Auth then builds upon that. This chart covers the differences:

Overview#

An API key authenticates an application component to give it access to Supabase services. An application component might be a web page, a mobile app, or a server. The API key does not distinguish between users, only between applications.

There are 4 types of API keys that you can use with Supabase:

Publishable keys#

Publishable keys identify the public components of your application. Public components run in environments where it is impossible to secure any secrets. These include:

• Web pages, where the key is bundled in source code.
• Mobile or desktop applications, where the key is bundled inside the compiled packages or executables.
• CLI, scripts, tools, or other pre-built executables.
• Other publicly available APIs that return the key without prior additional authorization.

These environments are always considered public because anyone can retrieve the key from the source code or build artifacts.

Interaction with Supabase Auth#

Using a publishable key does not mean that your user is anonymous. You can authenticate your application with the publishable key, while your user is authenticated (via Supabase Auth) with their personal JWT:

Security considerations#

Publishable keys are not intended to protect from the following, since key retrieval is always possible from a public component:

• Static or dynamic code analysis and reverse engineering attempts.
• Use of the Network inspector in the browser.
• Cross-site request forgery, cross-site scripting, phishing attacks.
• Man-in-the-middle attacks.

When using a publishable key, access to your project's data is guarded by Postgres via the built-in anon and authenticated roles. For full protection make sure:

• You have enabled Row Level Security on all tables.
• You regularly review your Row Level Security policies for permissions granted to the anon and authenticated roles.
• You do not modify the role's attributes without understanding the changes you are making.

Your project's Security Advisor constantly checks for common security problems with the built-in Postgres roles. Make sure you carefully review each finding before dismissing it.

What secret keys allow access to#

Unlike publishable keys, secret keys allow elevated access to your project's data. It is meant to be used only in secure, developer-controlled components of your application, such as:

• Servers that implement prior authorization themselves, such as Edge Functions, microservices, traditional or specialized web servers.
• Periodic jobs, queue processors, topic subscribers.
• Admin and back-office tools, with prior authorization checks only.
• Data processing pipelines, such as for analytics, reports, backups, or database synchronization.

Secret keys authorize access to your project's data via the built-in service_role Postgres role. By design, this role has full access to your project's data. It also uses the BYPASSRLS attribute, skipping any and all Row Level Security policies you attach.

The secret key is an improvement over the old JWT-based service_role key, and we recommend using it where possible. It adds more checks to prevent misuse, specifically:

• You cannot use a secret key in the browser (matches on the User-Agent header) and it will always reply with HTTP 401 Unauthorized.
• You don't need to have any secret keys if you are not using them.

Best practices for handling secret keys#

Below are some starting guidelines on how to securely work with secret keys:

• Always work with secret keys on computers you fully own or control.
• Use secure & encrypted send tools to share API keys with others (often provided by good password managers), but prefer the Settings > API Keys section of the Dashboard instead.
• Prefer encrypting them when stored in files or environment variables.
• Do not add in source control, especially for CI scripts and tools. Prefer using the tool's native secrets capability instead.
• Prefer using a separate secret key for each separate backend component of your application, so that if one is found to be vulnerable or to have leaked the key you will only need to change it and not all.
• Even though a secret key will always return HTTP 401 Unauthorized error when used in a browser, it does not mean that attackers will not use it with other tools. Delete immediately!
• If you must include them in logs, log the first few random characters (but never more than 6).
• If you wish to log or store which valid API key was used, store it as a SHA256 hash.

What to do if a secret key or service_role has been leaked or compromised?#

Don't rush if this has happened, or you are suspecting it has. Make sure you have fully considered the situation and have remediated the root cause of the suspicion or vulnerability first. Consider using the OWASP Risk Rating Methodology as an easy way to identify the severity of the incident and to plan your next steps.

To rotate a secret key (sb_secret_...), use the Settings > API Keys section of the Dashboard to create a new secret API key, then replace it with the compromised key. Once all components are using the new key, delete the compromised one.

Deleting a secret key is irreversible and once done it will be gone forever.

If you are still using the JWT-based service_role key, replace the service_role key with a new secret key instead. Follow the guide from above as if you are rotating an existing secret key.

Known limitations and compatibility differences#

As the publishable and secret keys are no longer JWT-based, there are some known limitations and compatibility differences that you may need to plan for:

• You cannot send a publishable or secret key in the Authorization: Bearer ... header, except if the value exactly equals the apikey header. In this case, your request will be forwarded down to your project's database, but will be rejected as the value is not a JWT.
• Edge Functions only support JWT verification via the anon and service_role JWT-based API keys. You will need to use the --no-verify-jwt option when using publishable and secret keys. The Supabase platform does not verify the apikey header when using Edge Functions in this way. Implement your own apikey-header authorization logic inside the Edge Function code itself.
• Public Realtime connections are limited to 24 hours in duration, unless the connection is upgraded and further maintained with user-level authentication via Supabase Auth or a supported Third-Party Auth provider.