How to Sync Supabase Auth Settings

Why Auth Settings Drift

Supabase auth configuration lives in the dashboard and the Management API, not in your migrations. Enable a sign-in provider in staging, turn on MFA or change the JWT expiry, and the change stays in that project. Nothing carries it forward.

The result: production quietly runs with different sign-in options, a missing MFA factor or a different session lifetime from the environment you tested in.

What SupaForge Checks

The auth check reads each project's full auth configuration and reports every setting that differs, with both values. Differences in the settings that decide how users get in are critical:

• Sign-in methods - email and phone sign-in, and whether new sign-ups are allowed.
• MFA - each factor's enrolment and verification (TOTP, phone, WebAuthn).
• Sessions - JWT expiry.
• Protection - CAPTCHA, and reauthentication before a password change.

Everything else - OAuth providers, password rules, rate limits, email templates, hooks and so on - is reported for information.

Step 1 - Configure Environments

The auth check uses the Management API, so each environment needs its projectRef and a Supabase personal access token in accessToken. Without them the check reports itself as skipped, never as clean.

npm install -g @akal/supaforge

{
  "environments": {
    "staging": {
      "dbUrl": "$STAGING_DATABASE_URL",
      "projectRef": "STAGING_REF",
      "accessToken": "$SUPABASE_ACCESS_TOKEN"
    },
    "production": {
      "dbUrl": "$PRODUCTION_DATABASE_URL",
      "projectRef": "PROD_REF",
      "accessToken": "$SUPABASE_ACCESS_TOKEN"
    }
  },
  "source": "staging",
  "target": "production"
}

On self-hosted Supabase, set apiUrl to the gateway and accessToken to the service-role key instead. The settings are read from GoTrue, which can't be written to, so drift there is fixed in the deployment's environment.

Step 2 - Compare

supaforge diff --check=auth --detail

Each finding names the setting (for example jwt_exp or mfa_totp_enroll_enabled), the source and target values, and its severity.

Step 3 - Sync

Fixes are applied through the Management API, one setting at a time. Preview them first:

supaforge diff --check=auth --apply --dry-run

supaforge diff --check=auth --apply

Best Practices

• Keep tokens out of the config file. Write "$SUPABASE_ACCESS_TOKEN" and set the value in your environment, a .env file or CI secrets.
• Roll out MFA deliberately. Requiring a factor in production affects users who haven't enrolled one yet - try it in staging first.
• Run it on a schedule. Auth settings change rarely, so drift goes unnoticed for a long time when it does happen.

Summary

Auth configuration rarely shows up in code review. SupaForge compares the whole of it, flags the differences that change who can get in, and syncs them through the Management API after you've reviewed them.