Supabase Service Role Key vs Anon Key: The Header Decides

My Supabase project was created on 2026-07-28. According to the timetable Supabase published for its API key change, a project that new should not have an anon key or a service_role key at all: from November 2025, "new projects no longer have anon and service_role available for use." Mine has both. They are the long JWT strings the docs now call legacy, they are what every script in this repository sends, and they expire on 2036-07-27. So before answering which key to use, I had to find out what the two keys I actually hold do, because the current docs describe a pair I apparently should not have been issued.

I spent fifteen requests on that on 2026-09-04. The result that matters most: on the REST data API, the service_role key does nothing if you put it in the apikey header alone. Row Level Security blocked it exactly as it blocks anon. The role comes from the Authorization header, and apikey is only a gate. That one detail is the likely answer to "supabase service role key not bypassing rls", which Google autocompletes for people typing the key's name.

What the two keys are

Both keys are JSON Web Tokens signed with HS256 by the project's JWT secret. Decoding mine gives the same four claims in each, and the only difference is one word:

{"iss":"supabase","ref":"urdufxfyqdrzphohfqop","role":"anon",        "iat":1785207700,"exp":2100783700}
{"iss":"supabase","ref":"urdufxfyqdrzphohfqop","role":"service_role","iat":1785207700,"exp":2100783700}

exp minus iat is 315,576,000 seconds, which is ten years to the second. The discussion that announced the new key format lists "JWTs had 10-year expiry duration, giving malicious actors more to work with" as one of nine reasons for replacing them. The role claim is a Postgres role name. When PostgREST accepts the token it runs your query as that role, and Row Level Security policies are the definition of what anon may do. service_role is a role that RLS does not apply to, which is the whole reason it must stay off the client.

The replacements are sb_publishable_… and sb_secret_…, described in the API keys guide as "short strings, not JWTs". Publishable maps to anon, secret maps to service_role, and the guide says Supabase "is deprecating the anon and service_role keys by the end of 2026". I cannot tell you whether my project also has the new pair, because both tools I have for listing keys refused. The Supabase MCP server returned "You do not have permission to perform this action", and supabase projects api-keys from CLI 2.110.0 returned 403, "Your account does not have the necessary privileges to access this endpoint". The CLI's error class is named LegacyProjectsApiKeysUnexpectedStatusError, so the endpoint it hit is the legacy one. Listing projects with the same login works.

Which header carries the role

To see which role a request runs as without storing anything, I sent an INSERT into post_faqs with a post_id that does not exist. Under anon the row is stopped by RLS first and Postgres returns error 42501. Under service_role RLS is skipped and the foreign key fails instead, error 23503. Either way nothing is written, and the error code names the role. Here is the matrix from 2026-09-04, about 12:10 KST, against /rest/v1/post_faqs:

apikey header	Authorization header	HTTP	Error	Ran as
none	none	401	No API key found in request	rejected at gateway
anon	none	401	42501 new row violates row-level security policy	anon
service_role	none	401	42501 new row violates row-level security policy	anon
none	Bearer service_role	401	No API key found in request	rejected at gateway
anon	Bearer service_role	409	23503 violates foreign key constraint	service_role
service_role	Bearer anon	401	42501	anon
service_role	Bearer service_role	409	23503	service_role
service_role as ?apikey= URL param	none	401	42501	anon
anon	Bearer notajwt	401	PGRST301 Expected 3 parts in JWT; got 1	rejected by PostgREST
anon	Bearer sb_secret_… (made up)	401	PGRST301 Expected 3 parts in JWT; got 1	rejected by PostgREST
garbage string	none	401	Invalid API key	rejected at gateway

Rows 3 and 5 are the answer. The gateway accepts any valid project key in apikey and forwards the request, then PostgREST reads Authorization to decide the role, and when that header is missing it falls back to anon no matter which key opened the gate. Put service_role in apikey and anon in Authorization and you get anon. Swap them and you get service_role. So a client that reads "service role key" and sets one header is running as the public role while believing it has bypassed RLS, and its writes fail with the same 42501 a browser would get.

The last three rows are what the new keys will look like to anyone who puts them in the wrong place. PostgREST wants three dot-separated parts, and sb_secret_… has none, so the error is "Expected 3 parts in JWT; got 1". That is the mechanism behind the discussion's line that using a publishable or secret key in the Authorization header "is no longer possible" because "they are not a JWT", with one exception: "it is only allowed if the value in the header exactly matches the value in the apikey header". I could not test that exception without a new-format key.

Three surfaces, three rules

The data endpoint is not the only reader of these headers, and the other two read them differently. The OpenAPI document at GET /rest/v1/ refused the anon key with "Only the service_role API key can be used for this endpoint", and it made that decision on the apikey header: anon in apikey with service_role in Authorization was still 401, while the reverse combination returned the schema with eight paths. Storage is a third rule. GET /storage/v1/bucket with only an apikey header, either key, answered 400 with headers must have required property 'authorization'. With Authorization: Bearer and the service_role token it listed my one bucket; with the anon token it returned an empty list, which is the correct answer for a role that owns nothing.

That third rule is already biting people who migrated. A report filed on 2026-08-08 against Supabase's own agent skill describes it: after moving a server upload from service_role to sb_secret_, "a raw Storage REST upload may still reject an apikey-only request because an authorization header is required", while putting the secret in Bearer produced "Invalid Compact JWS". The docs' instruction to send new keys "on the apikey header, not on Authorization: Bearer" is correct for the data API and leaves Storage's mandatory header unexplained. The migration guide names one more place the old habit breaks: Database Webhooks and pg_net calls "usually send the service_role key on the Authorization: Bearer header", and "the new secret keys aren't JWTs, so they're rejected there".

What the timetable says, and what two projects show

The announcement discussion opened on 2024-09-12 and has 69 comments; its status line was last updated on 2025-06-17 to say early access had launched. The timetable has four rows. June 2025 was the early preview, with new projects getting both key families. July 2025 was the full launch. November 2025 brought monthly migration reminders, no legacy keys for restored projects, and "New projects no longer have anon and service_role available for use". The last row is "Late 2026, TBC", when legacy keys are deleted. The changelog copy of that post, still linked from search results, returns 404, so the discussion is the only primary copy I could read.

Against the November row I have two data points. Mine: project created 2026-07-28 03:01 UTC, both legacy JWTs issued at that same second, which is what iat records, and still accepted on 2026-09-04. Someone else's: issue #48288, filed 2026-07-24, lists a hosted project "created 2026-07-23" whose environment includes "Legacy JWT-format anon / service_role API keys: disabled". You cannot disable keys you were never issued. Two projects created eight months after the cutoff both received the legacy pair. I read that as the milestone having slipped without the table being edited, not as two special cases, but I have no statement from Supabase saying so, and the "end of 2026" sentence in the current docs is the one to plan around.

The same issue is a preview of what changes when you do move. The reporter's project signed tokens with ES256, had legacy keys switched off, and found that sb_secret_ in apikey alone let Auth Admin reads through and rejected Auth Admin writes with bad_jwt. A later one, #49655 from 2026-08-27, reports intermittent PGRST303 JWT issued at future on requests that carried only an sb_secret_ key, and the reporter's theory is that the gateway mints a short-lived JWT from the opaque key before handing it to PostgREST. If that is right, the JWT did not go away. It moved server-side, and the Authorization rules above are still doing the work behind the new format.

What this repository does with the two keys

Five scripts touch Supabase. Three read with anon: the site builder, the deploy script and the weekly analytics snapshot. Two write with service_role: the thumbnail generator and the product image uploader. All five set both headers to the same key, for example make-thumbnails.py line 136:

h = {"Authorization": f"Bearer {k}", "apikey": k}

I did not choose that after understanding the matrix. It is the shape every Supabase example uses, and the matrix is why the examples look like that. It also means the migration is mechanical for the read side and not for the write side. Swapping anon for sb_publishable_ only needs the Authorization line removed. Swapping service_role for sb_secret_ needs the same removal on the data API, an Authorization header of some kind kept for Storage, and a check that no call runs from a browser, since the docs say a secret key there gets 401 "matched on the User-Agent header".

Four earlier posts on this site depend on the distinction. Testing RLS with the anon key compares a blocked DELETE and a real one, and both requests in it carry the key in both headers; had the service_role probe used apikey alone, the "real" delete would have been blocked too and the test would have proved nothing. The CMS post made the decision that only the two writers hold service_role and the build holds anon, the 1,000-row post is the paging code that uses the anon pair, and the free tier post is where the project's quotas are tracked. None of them needs correcting after today, which I checked before writing this.

FAQ

What is the difference between the Supabase service role key and the anon key?

Both are ten-year JWTs signed with the project's JWT secret, and the only claim that differs is role: anon or service_role. PostgREST runs the request as that Postgres role, so Row Level Security applies to anon and restricts it to what your policies allow, while service_role skips RLS entirely and must never reach a browser. Their replacements are the publishable key and the secret key, which are short opaque strings rather than JWTs.

Why is my service role key not bypassing RLS?

Most likely it is only in the apikey header. On the REST data API that header is a gate that accepts any valid key, and the role is read from Authorization: Bearer; when that header is absent the request runs as anon, so RLS applies and writes fail with error 42501. Send the service_role JWT in both headers. With the new sb_secret_ format the rule inverts: it goes in apikey only, because PostgREST rejects a non-JWT in Authorization with "Expected 3 parts in JWT; got 1".

Are the Supabase anon and service_role keys deprecated?

Yes. The API keys guide says Supabase is deprecating them by the end of 2026, and the announcement timetable lists deletion as "Late 2026, TBC". The same timetable says new projects stopped receiving them in November 2025, but a project created on 2026-07-28 and another reported as created on 2026-07-23 both received them, so that milestone has not held in practice. Existing keys keep working until you disable them in the dashboard or Supabase removes them.

Every status code and error message above comes from requests I sent to my own project on 2026-09-04 between 12:05 and 12:20 KST with curl 8.7.1 from a Mac mini in Seoul; the probe was an INSERT with a non-existent foreign key so that nothing was written under either role, and I confirmed the table afterwards. The JWT claims are decoded from the two keys in my .env. Supabase's statements are quoted from the announcement discussion, the API keys guide and the migration guide as read the same day, and the community reports are GitHub issues in the supabase and agent-skills repositories with the dates given. I could not list my project's keys through the MCP server or the CLI, so whether it also holds a publishable or secret key is unknown to me, and I did not test any new-format key. No affiliate links in this post.