Use Firebase, Supabase, Or Auth0 Sign-In With Persistly Cloud Saves

Auth Bridge is for games that already use Firebase Auth, Supabase Auth, or Auth0 and want Persistly to handle cloud saves, slots, sync, and conflicts.

The flow is intentionally short:

1. The game signs the player in with Firebase Auth, Supabase Auth, or Auth0.
2. The game gets a provider token from the Firebase, Supabase, or Auth0 SDK.
3. The Persistly SDK exchanges that token for a Persistly accountId and accountSessionToken.
4. The game keeps using normal Persistly save and sync helpers.

Persistly Auth Bridge is not a login UI. Firebase, Supabase, or Auth0 still owns player sign-in screens, credentials, password reset, social provider setup, and identity UX.

There are two common account flows:

• authRequired: the game asks the player to sign in before cloud sync. Use the Auth Bridge sign-in helper, then save and load with the returned Persistly account session.
• anonymousFirst: the game lets the player save immediately, then connects that existing Persistly account to Firebase, Supabase, or Auth0 later with a connect helper.

Free workspaces can test Auth Bridge with Stage runtime keys. Production Auth Bridge requires a paid workspace plan. See Persistly pricing for the plan distinction and Persistly features for the product overview.

Configure Auth Bridge In Persistly

Open your project in the Persistly dashboard and configure Authentication per environment.

Start with Stage:

• add Firebase Auth, Supabase Auth, or Auth0
• enter the provider setting for the project or tenant that signs in your test build
• use the dashboard test panel to verify the Stage configuration

Repeat the setup for Production only when your production build and paid workspace plan are ready.

Stage and Production stay separate because runtime keys select the Persistly environment. Use ps_test_ keys while developing and ps_live_ keys only in production builds.

Provider Setup Notes

For Firebase Auth:

• enter the Firebase project ID from Firebase project settings
• do not enter a Google OAuth client ID
• send Firebase ID tokens only to the Auth Bridge sign-in call

For Supabase Auth:

• enter the Supabase project URL, such as https://your-project-ref.supabase.co
• leave audience empty unless your Supabase project uses a non-default JWT audience
• do not paste Supabase anon keys, service-role keys, JWT secrets, database URLs, or API keys into Persistly

For Auth0:

• enter the Auth0 tenant domain, such as your-tenant.us.auth0.com
• set audience only when your game sends Auth0 API access tokens instead of ID tokens
• keep Allowed Callback URLs, Allowed Web Origins, and Allowed Logout URLs pointed at your game/app URLs, not Persistly URLs
• do not paste Auth0 client secrets, management API tokens, private keys, or OAuth client secrets into Persistly

Read the full provider docs at docs.persistly.app/auth.

Browser Game Flow

Use the Firebase, Supabase, or Auth0 SDK in the browser to sign in the player and retrieve a token. Then pass that token to Persistly.

import { PersistlyGameSaves } from "@persistlyapp/sdk";

await PersistlyGameSaves.configure({
  runtimeKey: "ps_test_replace_me",
  accountMode: "authRequired",
});

const providerToken = await getProviderTokenFromYourSignInFlow();

await PersistlyGameSaves.shared.signInWithProvider({
  provider: "firebase",
  token: providerToken,
  deviceLabel: "browser",
});

await PersistlyGameSaves.shared.saveData({
  level: 8,
  coins: 1800,
  checkpoint: "harbor",
});

await PersistlyGameSaves.shared.forceSyncData();

Use provider: "supabase" for Supabase access tokens and provider: "auth0" for Auth0 ID tokens or configured-audience access tokens.

After sign-in, the browser game does not send provider tokens to normal save, load, or sync routes. Those calls use the Persistly account session returned by Auth Bridge.

Unity Flow

In Unity, use your provider integration to get the player token, then call the Persistly helper before saving.

using Persistly.Unity;

await PersistlyGameSaves.ConfigureAsync(new PersistlyGameSavesSettings("ps_test_replace_me")
{
    AccountMode = PersistlyAccountMode.AuthRequired,
});

var firebaseIdToken = await GetFirebaseIdTokenAsync();
await PersistlyGameSaves.Shared.SignInWithFirebaseTokenAsync(firebaseIdToken);

await PersistlyGameSaves.Shared.SaveDataAsync(new PlayerData
{
    Level = 8,
    Coins = 1800,
    Checkpoint = "harbor",
});

await PersistlyGameSaves.Shared.ForceSyncDataAsync();

Use the Supabase or Auth0 helpers when your game signs in with those providers. Keep provider tokens out of Unity logs, crash reports, analytics, and support screenshots.

Godot Flow

In Godot, get the provider token from your plugin or game-owned auth layer, then sign in to Persistly before saving.

const PersistlyGameSaves = preload("res://addons/persistly/persistly_game_saves.gd")

var persistly := PersistlyGameSaves.new()
persistly.configure({
  "runtime_key": "ps_test_replace_me",
  "account_mode": "authRequired",
})

var firebase_id_token := await get_firebase_id_token()
await persistly.sign_in_with_firebase_token(firebase_id_token)

persistly.save_data({
  "level": 8,
  "coins": 1800,
  "checkpoint": "harbor",
})

persistly.force_sync_data()

Persistly stores game save state and account sessions. Firebase, Supabase, or Auth0 remains the identity system.

Account Modes

Use authRequired when the game requires sign-in before cloud sync. In this mode, the provider sign-in happens first and the Auth Bridge sign-in helper creates or resumes the Persistly account session.

Some games let players start immediately and sign in later. Use anonymousFirst for that flow. Save and sync the anonymous progress first, then call a connect-later helper after Firebase, Supabase, or Auth0 signs the player in.

Do not silently merge anonymous progress into an existing provider-linked account. If Auth Bridge returns account_auth_conflict, Persistly keeps the current local anonymous account and cache intact. Show recovery UI instead of clearing or overwriting local progress.

await PersistlyGameSaves.configure({
  runtimeKey: "ps_test_replace_me",
  accountMode: "anonymousFirst",
});

await PersistlyGameSaves.shared.saveData(localProgress);
await PersistlyGameSaves.shared.forceSyncData();

const firebaseIdToken = await getFirebaseIdTokenFromFirebaseAuth();

try {
  await PersistlyGameSaves.shared.connectWithFirebaseToken(firebaseIdToken);
} catch (error) {
  if (error && typeof error === "object" && "code" in error && error.code === "account_auth_conflict") {
    showKeepLocalOrSwitchAccountUI(error.details);
    return;
  }

  throw error;
}

Use connectWithSupabaseToken, connectWithAuth0Token, or connectProvider for the same connect-later flow with other providers. Persistly never silently merges two accounts.

Sign Out

Sign-out should do two things:

• sign out through Firebase, Supabase, or Auth0 so the game returns to signed-out UI
• clear the local Persistly account/session/slot cache on that device

This is local cleanup. It does not delete the remote Persistly account, and it does not revoke provider sessions.

Common Errors

Security Checklist

• Never log provider tokens.
• Never log Persistly account session tokens.
• Do not store provider tokens as save identifiers.
• Do not send provider tokens to normal save/load/sync routes.
• Use Stage keys for QA and Production keys only in release builds.
• Keep payment validation, competitive economy authority, and anti-cheat-sensitive data in a trusted backend.

Next Step

Read the full Auth Bridge docs at docs.persistly.app/auth, then choose anonymousFirst or authRequired for your game flow.