Supabase Auth

You can implement various types of authentication when using PowerSync with Supabase:

Standard Supabase Auth

These examples show how to implement fetchCredentials() in your client-side backend connector to get the Supabase JWT from the Supabase Client Library:

Anonymous Sign-Ins

This examples shows use of Supabase’s signInAnonymously() and then the implementation of fetchCredentials() to get the JWT from the Supabase Client Library:

JavaScript example

Fully Custom Auth

This example shows how to implement Supabase Edge Functions to generate custom JWTs for PowerSync (either for signed-in users or anonymous users) as well as expose a JWKS endpoint:

Example

External Auth Providers

We’ve heard from the community that Supabase’s support for third-party auth providers works with PowerSync, but we don’t have any examples for this yet.

Supabase JWT Signing Keys

Supabase supports two types of JWT signing keys:

Type	Algorithm	Description
Legacy JWT signing keys	HS256 (symmetric)	Uses a shared secret to sign and verify tokens. This is the original method.
New JWT signing keys	RS256 (asymmetric)	Uses public/private key pairs. Supabase signs tokens with a private key, and PowerSync verifies them using a public key fetched via JWKS.

PowerSync supports both methods. Which configuration you need depends on your Supabase project’s JWT settings and your PowerSync deployment type.

To check which signing keys your Supabase project uses, go to Project Settings > JWT in your Supabase Dashboard.

PowerSync Cloud

When using PowerSync Cloud with a Supabase-hosted database, PowerSync can auto-detect your Supabase project from the database connection string and configure authentication automatically.

New JWT Signing Keys (Recommended)
Legacy JWT Signing Keys
Manual JWKS Configuration

Using New JWT Signing Keys

This is the recommended approach for Supabase projects using asymmetric JWT signing keys.

In the PowerSync Dashboard, select your project and instance and go to the Client Auth view.
Enable the Use Supabase Auth checkbox.
Leave the Supabase JWT Secret field empty (it’s not needed for new keys).
Click Save and Deploy.

PowerSync auto-detects your Supabase project from the database connection string and configures the JWKS URI (https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json) and JWT audience (authenticated) automatically.

Manual JWKS Configuration

Use manual configuration when PowerSync cannot auto-detect your Supabase project. This happens when:

You’re using a non-standard database connection string
You’re connecting to a self-hosted Supabase instance
You’re using Supabase local development (Docker)

Steps:

In the PowerSync Dashboard, go to the Client Auth view.
Leave the Use Supabase Auth checkbox unchecked.

Add a JWKS URI, e.g.:

http://localhost:54321/auth/v1/.well-known/jwks.json

Add authenticated as an accepted JWT Audience.
Click Save and Deploy.

If you skip adding the authenticated audience, you will see PSYNC_S2105 errors (“JWT payload is missing a required claim ‘aud’”).

Self-Hosted PowerSync

For self-hosted PowerSync instances, configure authentication in your service.yaml.

New JWT Signing Keys (Recommended)
Legacy JWT Signing Keys
Manual JWKS Configuration

Using New JWT Signing Keys

When using a standard Supabase connection string, PowerSync auto-detects your Supabase project:

client_auth:
  supabase: true

PowerSync will automatically configure:

JWKS URI: https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json
Audience: authenticated

You’ll see a log message confirming the configuration:

Configured Supabase Auth with https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json

Using Legacy JWT Signing Keys

Legacy JWT signing keys use HS256 (symmetric encryption with shared secrets), which is less secure than asymmetric keys. We recommend migrating to new JWT signing keys for better security.

For projects using legacy HS256 symmetric signing keys, provide your JWT secret:

client_auth:
  supabase: true
  supabase_jwt_secret: your-jwt-secret-here

Get your JWT secret from your Supabase project’s JWT settings.

Manual JWKS Configuration

Use manual configuration in any of these scenarios:

PowerSync cannot detect your Supabase project from the connection string
You’re using self-hosted Supabase
You’re using Supabase local development (Docker)
You need explicit control over the authentication settings

client_auth:
  jwks_uri: http://localhost:54321/auth/v1/.well-known/jwks.json
  audience:
    - authenticated

When using manual configuration, do not set supabase: true. Use jwks_uri and audience directly.

Migrating from Legacy to New JWT Signing Keys

If you’re migrating your Supabase project from legacy JWT signing keys to the new asymmetric keys:

Step 1: Complete the Supabase Migration

Follow all steps in Supabase’s JWT signing keys migration guide, including the “Rotate to asymmetric JWTs” step.

The migration is not complete until you complete the “Rotate to asymmetric JWTs” step in Supabase. Skipping this step will cause authentication failures.

Step 2: Update PowerSync Configuration

For PowerSync Cloud and self-hosted with standard Supabase connections:

No changes required. PowerSync auto-detects and uses the new JWKS endpoint.
If you previously provided a legacy JWT secret, you can remove it (it’s no longer needed).

For manual JWKS configurations:

Ensure your JWKS URI (jwks_uri) points to your Supabase JWKS endpoint.
Verify the authenticated JWT Audience (audience) is configured.

Step 3: Clear Cached Tokens

Have all users sign out and sign back in. This ensures they receive new tokens signed with the asymmetric keys.

Troubleshooting

Debugging error codes:

`PSYNC_S2101`: Could not find an appropriate key in the keystore

This error indicates PowerSync cannot verify the JWT signature. Common causes:

Cause	Solution
Incomplete Supabase migration	Complete the “Rotate to asymmetric JWTs” step in Supabase’s migration guide.
Cached tokens	Have users sign out and sign back in to get fresh tokens.
Non-standard connection string	PowerSync couldn’t auto-detect your Supabase project. Use manual JWKS configuration.
Wrong JWT secret	For legacy keys, verify the JWT secret matches your Supabase project settings.

`PSYNC_S2105`: JWT payload is missing a required claim “aud”

This error occurs when using manual JWKS configuration without specifying an audience. Add authenticated to your audience configuration.

Auto-Detection Not Working

If PowerSync logs this warning:

Supabase Auth is enabled, but no Supabase connection string found. Skipping Supabase JWKS URL configuration.

This means PowerSync couldn’t detect your Supabase project from the database connection string. Use manual JWKS configuration instead.

Sync Streams

The Supabase user UUID will be available as:

auth.user_id() in Sync Streams.
request.user_id() in Sync Rules

To use a different identifier as the user ID in Sync Streams / Sync Rules (for example, user email), use Custom Authentication.

Get Started

Configuration Details

Sync Streams & Rules

Client SDKs

Handling Writes

Maintenance & Ops

Integrations

Tools

Resources

Standard Supabase Auth

Anonymous Sign-Ins

Fully Custom Auth

External Auth Providers

Supabase JWT Signing Keys

PowerSync Cloud

Using New JWT Signing Keys

Using Legacy JWT Signing Keys

Manual JWKS Configuration

Self-Hosted PowerSync

Using New JWT Signing Keys

Using Legacy JWT Signing Keys

Manual JWKS Configuration

Migrating from Legacy to New JWT Signing Keys

Step 1: Complete the Supabase Migration

Step 2: Update PowerSync Configuration

Step 3: Clear Cached Tokens

Troubleshooting

`PSYNC_S2101`: Could not find an appropriate key in the keystore

`PSYNC_S2105`: JWT payload is missing a required claim “aud”

Auto-Detection Not Working

Sync Streams

​Standard Supabase Auth

​Anonymous Sign-Ins

​Fully Custom Auth

​External Auth Providers

​Supabase JWT Signing Keys

​PowerSync Cloud

​Using New JWT Signing Keys

​Using Legacy JWT Signing Keys

​Manual JWKS Configuration

​Self-Hosted PowerSync

​Using New JWT Signing Keys

​Using Legacy JWT Signing Keys

​Manual JWKS Configuration

​Migrating from Legacy to New JWT Signing Keys

​Step 1: Complete the Supabase Migration

​Step 2: Update PowerSync Configuration

​Step 3: Clear Cached Tokens

​Troubleshooting

​PSYNC_S2101: Could not find an appropriate key in the keystore

​PSYNC_S2105: JWT payload is missing a required claim “aud”

​Auto-Detection Not Working

​Sync Streams

Standard Supabase Auth

Anonymous Sign-Ins

Fully Custom Auth

External Auth Providers

Supabase JWT Signing Keys

PowerSync Cloud

Using New JWT Signing Keys

Using Legacy JWT Signing Keys

Manual JWKS Configuration

Self-Hosted PowerSync

Using New JWT Signing Keys

Using Legacy JWT Signing Keys

Manual JWKS Configuration

Migrating from Legacy to New JWT Signing Keys

Step 1: Complete the Supabase Migration

Step 2: Update PowerSync Configuration

Step 3: Clear Cached Tokens

Troubleshooting

`PSYNC_S2101`: Could not find an appropriate key in the keystore

`PSYNC_S2105`: JWT payload is missing a required claim “aud”

Auto-Detection Not Working

Sync Streams