Realtime does not include global headers from createClient in WebSocket handshake — RLS policies that check request.headers fail

[IdrisCelik]

Describe the bug

Problem summary

When a client sets custom headers via createClient(..., { global: { headers: { 'x-rls': 'true' } } }), those headers are available on normal HTTP requests but are not present on the Realtime WebSocket connection used for Postgres postgres_changes events. If an RLS policy relies on current_setting('request.headers', true) (or otherwise expects that header during Realtime evaluation), the policy evaluates to false and the client receives no realtime messages. Turning RLS off makes the events deliver, confirming this is about missing connection metadata. This appears to be a mismatch between how the SDK sets global.headers (HTTP) and what the Realtime server actually receives during the WS handshake.

Why this is important

Developers commonly use custom headers for tenant identification or extra metadata in multi-tenant setups. RLS policies that depend on such headers work fine for REST requests (via request.headers) but break for Realtime because the WebSocket handshake from browsers doesn't carry arbitrary custom headers. That makes it difficult to implement secure, tenant-aware realtime subscriptions without embedding tenant info in the JWT or using other workarounds. These workarounds are bad since embedding the current tenant in JWT means that it breaks when wanting to use 2 different tenants on 2 different devices.

If websockets dont support headers, Supabase js sdk could just include the header as metadata when setting up the websocket and threat that as the header in RLS.

Library affected

supabase-js

Reproduction

No response

Steps to reproduce

Create following table with rls:

-- create table
create table public.realtime_test (
  id serial primary key,
  content text
);

-- enable RLS
alter table public.realtime_test enable row level security;

-- policy: allow SELECT only if header x-rls is present and equals 'true'
create policy "allow-select-if-x-rls-true" on public.realtime_test
  for select using (
    (current_setting('request.headers', true)::json ->> 'x-rls') = 'true'
  );

Have a client listen:

import { createClient } from '@supabase/supabase-js';

const SUPABASE_URL = 'https://your-project.supabase.co';
const SUPABASE_ANON_KEY = '...';

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
  // developer sets a custom header globally
  global: {
    headers: {
      'x-rls': 'true'
    }
  }
});

// subscribe to postgres changes
const channel = supabase
  .channel('public:realtime_test')
  .on('postgres_changes', { schema: 'public', table: 'realtime_test', event: 'INSERT' }, payload => {
    console.log('received payload', payload);
  })
  .subscribe();

Insert a row and observe in the network tab no message appearing inside the WS connection

System Info

System:
    OS: Windows 11 10.0.26100
    CPU: (16) x64 AMD Ryzen 7 7840HS w/ Radeon 780M Graphics
    Memory: 2.89 GB / 15.29 GB
  Binaries:
    Node: 22.18.0 - C:\nvm4w\nodejs\node.EXE
    npm: 11.5.2 - C:\nvm4w\nodejs\npm.CMD
    pnpm: 10.18.2 - C:\nvm4w\nodejs\pnpm.CMD
  Browsers:
    Chrome: 141.0.7390.108
    Edge: Chromium (139.0.3405.102)
  npmPackages:
    @supabase/supabase-js: ^2.75.0 => 2.75.0
    supabase: ^2.51.0 => 2.51.0

Used Package Manager

pnpm

Logs

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a Supabase JS Library issue and not an issue with the Supabase platform. If it's a Supabase platform related bug, it should likely be reported to supabase/supabase instead.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[nadjiel]

Hey! I think this issue is probably related to a problem I was facing just yesterday...

My struggle was that Realtime connections weren't emitting any events about a table, even when fetching data through the REST API from that same table successfully returned data.

The client I used was @supabase/ssr@0.7.0. Apparently, I was not being able to receive Realtime events because its client didn't take into account the user data, different from the REST client, which correctly included it in its requests.

This is the code I used to initialize the Supabase client:

export function createServerClient(req: Request, res: Response) {
  return supabaseSsr.createServerClient(
    config.supabaseUrl,
    config.supabaseAnonKey,
    {
      cookies: {
        getAll: async () =>
          Object.entries(req.cookies).map(([name, value]) => ({
            name,
            value,
          })),
        setAll: async (cookies) =>
          cookies.forEach(({ name, value, options }) => {
            res.cookie(name, value, {
              ...options,
              httpOnly: true,
              secure: false,
            });
          }),
      },
    }
  );
}

I had RLS policies activated for the table in question, but, like I said, they were working with REST requests. Only when it came to Realtime connections no events were emitted, as if the user had no access.

I created a thread in Supabase's Discord to discuss that and one moderator over there pointed to me that this is an unexpected behavior that some people are facing lately. He suggested a workaround that solved the problem for me, which consisted of calling the supabase.realtime.setAuth method, so that the Realtime client correctly knows the user data and uses it on its connections.

I created a Minimal Reproduction Example to showcase the issue, available here, in case that helps solving the problem. This MRE already includes the solution suggested for the bug, though, which was including supabase.realtime.setAuth() in this line.

I don't know if for your case just adding this would solve the problem, since yours seem to be a little different, but maybe it's worth trying! 🙂

[mandarini]

Thank you both, I am looking into it. @IdrisCelik can you please check and see if the fix suggested by @nadjiel works for you?

[mandarini]

@IdrisCelik after discussing with the team, I think your issue may be similar to this one. Can you try the approach suggested in this comment by @filipecabaco ? Essentially, use a custom JWT. Having the header as metadata would also increase the payload size, while custom JWT is still the best approach for multi-tenancy.

Check out the docs here:

• https://supabase.com/docs/guides/auth/auth-hooks/custom-access-token-hook
• https://supabase.com/docs/guides/auth/jwts?queryGroups=language&language=ts
  Specifically this: https://supabase.com/docs/guides/auth/jwts?queryGroups=language&language=ts#using-custom-or-third-party-jwts

[IdrisCelik]

Hey @nadjiel ,

Thanks for your reply. This is indeed also a issue with Realtime. But the issue you are talking about means the RLS policy will be eval as anon with auth.uid being null. And therefore failing. I also faced this issue before switching to multi tenancy and realtime.setAuth did indeed fix it, which I now still do onAuthChange. So this is a slightly different issue. But thanks for your suggestion!

[IdrisCelik]

Hey @mandarini ,

Thanks for looking into this!

Thank you both, I am looking into it. @IdrisCelik can you please check and see if the fix suggested by @nadjiel works for you?

Unfortunatly this doesn't fix this, I happen to do this already in my codebase.

I also just replied to your collegue's comment, but the proposed pattern wouldn't work for multi tenant apps, where the same user wants to be in diffferent orgs for different devices. Which is a common usecase that works really well with orgSlug.app.com. Where you just have to redirect them to a different domainname for them to switch tenants per device.

Perhaps a great way to solve this is to add a flag to global headers in createClient: includeRealtime.
If you set this to true the dev opts in to include that header in realtime. This will limit the payload increase, since its just one string more.

I hope this can be fixed, since this is a low cost solution, and will support more robust multi tenant setups. Because now you either have to have less robust tenant switching and multi device support. Or inefficient RLS policies that check data permissions for all your profiles across all tenants.

[IdrisCelik]

Hi @mandarini and @filipecabaco
I did some more digging, because I was curious how you currently sent the apikey, normally this is a header in fetches. But this can't be done with websockets in browsers. What you do is instead sent it as a queryParam in the url.

This solution would honestly work perfectly for this as well, it's basically no cost, you already do this, a string in the url doesnt matter for performance either, but if this is still a worry just add a flag in createClient > global > headers to optionally include it in realtime websocket. Now supabase realtime can use those query params as headers when evaluating RLS.

Now the most robust standard for multi tenant systems also work safely and performant with Supabase Realtime. And it barely costs developers time. This bug fix is of course incredibly important. Would love to hear your plans!

[filipecabaco]

We discussed this in our team and we really feel this is not the way to go as we will end up with security issues due to the nature of how Websockets work.

There's another suggestion where you would be able to use custom jwt tokens but with more complex claims. Here's the code example:

• Setup a policies to access and allow writes that checks the channel topic name contains one of the tenant id's that is present in the JWT claims

DROP POLICY IF EXISTS "Users can join channels for their tenants" ON realtime.messages;
DROP POLICY IF EXISTS "Users can send messages on their tenant channels" ON realtime.messages;

CREATE POLICY "Users can join channels for their tenants"
ON realtime.messages
FOR SELECT
TO authenticated
USING (
  (SELECT realtime.topic()) IS NOT NULL
  AND (SELECT realtime.topic()) LIKE 'tenant-%'
  AND REPLACE((SELECT realtime.topic()), 'tenant-', '')::int = ANY(
    ARRAY(
      SELECT jsonb_array_elements_text(
        (current_setting('request.jwt.claims', true)::json -> 'tenant_ids')::jsonb
      )::int
    )
  )
);

-- Policy: Allow users to send messages (broadcast) on channels for their tenants
CREATE POLICY "Users can send messages on their tenant channels"
ON realtime.messages
FOR INSERT
TO authenticated
WITH CHECK (
  realtime.messages.extension = 'broadcast'
  AND
  -- Extract tenant ID from topic (e.g., "tenant-1" -> 1)
  (SELECT realtime.topic()) IS NOT NULL
  AND (SELECT realtime.topic()) LIKE 'tenant-%'
  AND REPLACE((SELECT realtime.topic()), 'tenant-', '')::int = ANY(
    ARRAY(
      SELECT jsonb_array_elements_text(
        (current_setting('request.jwt.claims', true)::json -> 'tenant_ids')::jsonb
      )::int
    )
  )
);

• In the code, create the custom JWT token with a claim with the tenant ids and sign it with the secret

// For CLI usage, set the following environment variables:
// export SUPABASE_URL=http://localhost:54321
// export SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
// export JWT_SECRET=super-secret-jwt-token-with-at-least-32-characters-long
// run with: deno run --allow-env custom_jwt_realtime.ts
import { createClient } from "npm:@supabase/supabase-js@latest";
import { SignJWT } from "npm:jose@^5.2.0";

const SUPABASE_URL = Deno.env.get("SUPABASE_URL");
const SUPABASE_ANON_KEY = Deno.env.get("SUPABASE_ANON_KEY");
const JWT_SECRET = Deno.env.get("JWT_SECRET");

const TENANT_IDS = [1, 2, 3];
const USER_ID = "123e4567-e89b-12d3-a456-426614174000";

/**
 * Creates a custom JWT with tenant_ids claim for multi-tenancy
 */
async function createCustomJWT(tenantIds: number[]): Promise<string> {
  const issuer = `${SUPABASE_URL}/auth/v1`;
  const secret = new TextEncoder().encode(JWT_SECRET);

  const token = await new SignJWT({
    sub: USER_ID,
    aud: "authenticated",
    role: "authenticated",

    // Custom claim for multi-tenancy
    // This claim will be accessible in RLS policies via auth.jwt() -> 'tenant_ids'
    tenant_ids: tenantIds,
  })
    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
    .setIssuedAt()
    .setIssuer(issuer)
    .setExpirationTime("1h")
    .sign(secret);

  return token;
}

async function main() {
  const customJWT = await createCustomJWT(TENANT_IDS);
  const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, { customJWT });
  supabase.realtime.setAuth(customJWT);

  // Create a channel for each tenant ID
  TENANT_IDS.map((tenantId) => {
    const channelTopic = `tenant-${tenantId}`;
    const channel = supabase.channel(channelTopic, {
      config: { private: true, broadcast: { self: true } },
    });

    // Listen for broadcast messages on this channel
    channel.on("broadcast", { event: "*" }, (payload) =>
      console.log(`[${channelTopic}] Received broadcast:`, payload)
    );

    channel.subscribe((status) => {
      if (status === "SUBSCRIBED") {
        console.log(`Successfully subscribed to channel: ${channelTopic}`);
        setInterval(() => {
          channel.send({
            type: "broadcast",
            event: "ping",
            payload: {
              channel: channelTopic,
              timestamp: new Date().toISOString(),
            },
          });
        }, 2000);
      }
    });
  });

  // Create a channel for a tenant NOT in the JWT's tenant_ids claim to show failure
  const unauthorizedTenantId = 99;
  const unauthorizedChannelTopic = `tenant-${unauthorizedTenantId}`;
  const unauthorizedChannel = supabase.channel(unauthorizedChannelTopic, {
    config: { private: true, broadcast: { self: true } },
  });

  unauthorizedChannel.subscribe((status, err) => {
    if (status === "CHANNEL_ERROR") {
      console.log(
        `[${unauthorizedChannelTopic}] Correctly rejected: ${err?.message}`
      );
    }
  });
}

main().catch((error) => console.error(error));

This provides some extra layers of security as we are only using material that we are properly able to check the signatures and be sure that it was not tampered with.

We will add this to our troubleshooting guides as this feels like a very useful use case to cover and just showcase what a custom JWT is capable of doing but we are not moving forward with adding headers.