Added details on using the new JWT signing keys method

[bean1352]

Revised Supabase Auth documentation to clarify JWT signing key configurations and migration steps. Added details on using legacy and new JWT signing keys, including configuration examples and common migration issues. Updated troubleshooting section with specific error causes related to JWT signing key mismatches.

[benitav]

I'm not sure if you want feedback yet as this PR is still a draft, but unless I missed a recent change, the process for the new JWT signing keys is to ONLY check the Supabase Auth checkbox on the PowerSync side. No need to enter JWKS URI and Audience (that was a previous workaround).

[joshuabrink]

The Supabase auth checkbox is designed for Supabase's legacy symmetric keys (HS256) and requires the supabase_jwt_secret to function properly. When you enable the checkbox without providing the secret, PowerSync logs a warning and skips the Supabase configuration:

{"level":"warn","message":"Supabase Auth is enabled, but no Supabase connection string found. Skipping Supabase JWKS URL configuration.","timestamp":"2026-01-12T11:14:09.461Z"}

This causes PowerSync to fall back to any manually configured jwks_uri or jwks settings you've already provided. Which is why it appears to work when you only check the box.

However, for Supabase's new asymmetric JWT signing keys, the current approach is to leave the Supabase auth unchecked (or set supabase: false), then configure the jwks_uri: https://<your-project-ref>.supabase.co/auth/v1/.well-known/jwks.json or jwk like any other auth provider.

And you still need to add an authenticated audience (this is the default audience generated when doing sign-ins Supabase JWTs) or else you are going to see a PSYNC_S2105 error JWT payload is missing a required claim "aud".

[rkistner]

@joshuabrink That "Supabase connection string found" means you're not using a normal Supabase connection. If you're using a Supabase connection for the database, ticking that box will auto-configure the audience and jwks_uri.

[joshuabrink]

That makes sense, I found this function

Correct me if I'm wrong, but it's a simple regex detection, then rebuilding of the JWKS uri from the replication connection string, which should output a message like this if it succeeds:

 {"level":"info","message":"Configured Supabase Auth with https://foobar.supabase.co/auth/v1/.well-known/jwks.json","timestamp":"2026-01-12T13:34:57.035Z"}

Both methods work but I wasn't aware of the auto-configure, I've been testing on the local Supabase docker container. So yes, sorry I did miss that. The recommended approach is to just set supabase: true, unless you are using a non-conventional connection string (like in dev environments or self-hosting)

[rkistner]

Correct. I'm not sure if there is a nice way to auto-compute the config for local Supabase - haven't tried that yet.