How to Sync Supabase Auth Settings

Why Auth Settings Drift

Supabase auth configuration is managed through the Dashboard or Management API — not through migrations. When a developer enables Google OAuth in staging, adds an MFA policy, or changes the JWT expiry, those changes live only in that project. There is no built-in mechanism to promote them.

The result: production may have different OAuth redirect URIs, a missing MFA requirement, or an outdated JWT expiry that causes silent session failures.

What SupaForge Checks

The auth check compares over 20 configuration values between source and target:

• OAuth providers — enabled state, client IDs, redirect URIs for Google, GitHub, Apple, Azure, etc.
• MFA — TOTP/SMS factors, enforcement level (optional, required, or disabled).
• JWT — expiry duration, refresh token rotation, session lifetime.
• CAPTCHA — provider (hCaptcha, Turnstile), enabled state, site key.
• Email/SMS templates — confirmation, recovery, and invite templates.
• Rate limits — sign-up, sign-in, and token refresh limits.

Step 1 — Configure Environments

npm i -g @akalforge/supaforge

{
  "environments": {
    "staging": {
      "dbUrl": "postgresql://user:pass@db.STAGING_REF.supabase.co:5432/postgres",
      "projectRef": "STAGING_REF",
      "apiKey": "your-staging-service-role-key"
    },
    "production": {
      "dbUrl": "postgresql://user:pass@db.PROD_REF.supabase.co:5432/postgres",
      "projectRef": "PROD_REF",
      "apiKey": "your-production-service-role-key"
    }
  },
  "source": "staging",
  "target": "production"
}

Step 2 — Run an Auth-Only Scan

supaforge scan --check auth

The output groups differences by category (OAuth, MFA, JWT, CAPTCHA) and shows the source value, target value, and severity for each setting.

Step 3 — Review the Diff

For each setting, SupaForge displays:

• The setting key (e.g. external.google.enabled).
• Source value vs target value.
• Severity — critical for missing providers or MFA mismatch, warning for cosmetic differences.

Auth settings are applied through the Supabase Management API, not raw SQL. The promote step calls the API on the target project to sync each changed setting.

Step 4 — Promote Changes

supaforge promote

supaforge promote --check auth --apply

Best Practices

• Keep OAuth secrets out of config files. Use environment variables or a secrets manager. SupaForge compares enabled state and redirect URIs — not client secrets.
• Test MFA changes in staging first. Promoting an MFA requirement to production locks out users who haven't enrolled a factor.
• Schedule regular scans. Auth settings change infrequently, but even small drifts (JWT expiry, rate limits) can cause hard-to-debug production issues.

Summary

Auth configuration is invisible infrastructure — it rarely shows up in code reviews. SupaForge surfaces discrepancies so you can review and promote auth settings with the same confidence as schema changes.