Clerk URL Masking Strategies

Overview

When using Clerk's satellite domain architecture, sync parameters appear in URLs:

• __clerk_synced
• __clerk_db_jwt
• __clerk_hs_reason

While maintaining single sign-on (SSO), we can mask these parameters to create cleaner URLs.

Strategy 1: Simple Parameter Renaming

Map Clerk parameters to friendlier names:

• __clerk_db_jwt → session
• __clerk_synced → status
• __clerk_hs_reason → ref

Example:

Before: http://localhost:3005/?__clerk_synced=true&__clerk_db_jwt=xyz&__clerk_hs_reason=primary-responds-to-syncing
After:  http://localhost:3005/?status=true&session=xyz&ref=primary-responds-to-syncing

Strategy 2: Single Token Parameter

Use a UUID that maps to all sync parameters:

Example:

Before: http://localhost:3005/?__clerk_synced=true&__clerk_db_jwt=xyz&__clerk_hs_reason=primary-responds-to-syncing
After:  http://localhost:3005/?auth=550e8400-e29b-41d4-a716-446655440000

Strategy 3: Custom Sync Endpoint

Route through a custom endpoint that handles sync behind the scenes:

Example:

Before: http://localhost:3005/?__clerk_synced=true&__clerk_db_jwt=xyz
After:  http://localhost:3005/auth/callback?token=abc123

Implementation Details

Middleware Updates

The middleware now handles both original and masked parameters:

// Check for masked parameters
if (url.searchParams.has('session')) {
  // Convert to Clerk format
  clerkUrl.searchParams.set('__clerk_db_jwt', url.searchParams.get('session')!)
}

URL Cleaner

The ClerkUrlCleaner component removes both original and masked parameters after sync.

Production Considerations

1. Security: Masked parameters still contain sensitive data
2. Caching: Be careful with CDN caching of URLs with auth parameters
3. Performance: Parameter mapping adds minimal overhead

Recommended Approach

For the best balance of cleanliness and simplicity, we recommend:

1. Development: Use simple parameter renaming (Strategy 1)
2. Production: Consider custom sync endpoint (Strategy 3) or UUID tokens (Strategy 2)

This maintains SSO benefits while providing cleaner URLs for users.