supabase-clerk-sync

# Supabase-Clerk Sync

Comprehensive integration patterns for syncing Clerk authentication with Supabase databases, including JWT configuration, RLS policies, webhook setup, and user data synchronization.

## Instructions

### When Integrating Clerk with Supabase

1. **JWT Configuration Strategy**
   - Configure Supabase to validate Clerk JWT tokens
   - Extract Clerk JWT template from dashboard
   - Configure Supabase auth settings with Clerk JWKS endpoint
   - Map Clerk user claims to Supabase RLS policies
   - Handle JWT expiration and refresh flows

2. **User Sync Architecture**
   - Choose sync strategy: Webhook-based (recommended) or Client-side
   - Set up Clerk webhooks for user lifecycle events
   - Create Supabase tables for user profile data
   - Implement idempotent sync operations
   - Handle race conditions and eventual consistency

3. **RLS Policy Design**
   - Use Clerk `sub` claim as user identifier in policies
   - Extract user metadata from JWT for policy decisions
   - Implement role-based access with Clerk organizations
   - Create policies for user-owned resources
   - Test policies with different JWT claims

4. **Webhook Implementation**
   - Verify Clerk webhook signatures (svix library)
   - Handle user.created, user.updated, user.deleted events
   - Implement retry logic for failed syncs
   - Log sync operations for debugging
   - Use Supabase service role key for webhook operations

### Integration Workflow

**Phase 1: JWT Setup**
1. Get Clerk JWKS URL from dashboard
2. Configure Supabase auth.jwt_secret
3. Update Supabase JWT settings with Clerk issuer
4. Test JWT validation with sample tokens

**Phase 2: Database Schema**
1. Create users table with Clerk ID mapping
2. Add user metadata columns
3. Set up RLS policies using JWT claims
4. Create indexes for performance

**Phase 3: Webhook Configuration**
1. Deploy webhook endpoint (Supabase Edge Function or external)
2. Register webhook URL in Clerk dashboard
3. Select user events to sync
4