Firebase Auth

Firebase handles login. Persistly handles cloud-save sessions.

Auth Bridge is a short token exchange before normal save sync. Persistly verifies the Firebase ID token and returns accountId plus accountSessionToken for save/load routes.

Phase 1AFirebase ID tokenaccount sessions

Choose account mode Direct API example

Persistly Verification

What Persistly verifies

Persistly checks the Firebase token against the environment configuration selected by the runtime key.

Persistly verifies the Firebase token signature, issuer, audience, expiration, and stable subject.

Persistly uses the verified issuer and subject as the identity key. Email is never the account identity.

Normal save, load, and sync routes do not accept Firebase tokens. They use the Persistly account session returned by Auth Bridge.

Firebase Responsibility

What Firebase handles

Firebase remains the player identity system and token issuer for your game.

Firebase handles sign-in UI, user credentials, password reset, social sign-in setup, and token issuance.

Your game decides when to ask the player to sign in and when to refresh the Firebase ID token.

Persistly does not store Firebase ID tokens, replace Firebase user management, or revoke Firebase sessions.

Dashboard Setup

Enable Firebase Auth per environment.

Stage and Production have separate settings so test users and production players can stay isolated.

Create or choose the Firebase project your game already uses for player sign-in.

In the Persistly dashboard, open the project Authentication page and add Firebase Auth to Stage first.

Enter the Firebase project ID from Firebase project settings. Do not enter a Google OAuth client ID.

Paste a Firebase ID token into the dashboard test panel to verify the Stage configuration before using it in a game.

Use Free workspace Stage keys for testing. Upgrade before using Production Auth Bridge with live players.

Repeat the same review for Production only after the production build and Firebase settings are ready.

Use the Firebase Auth SDK in the game to obtain a Firebase ID token for the signed-in player.

Pass that ID token to the Persistly SDK auth helper, then continue using normal save and load helpers.

Configure Stage first with a stage runtime key, then repeat the review for Production when the production build is ready.

Free workspaces can test Firebase Auth Bridge on Stage. Production Auth Bridge requires a paid workspace plan.

Use the Firebase project ID from the Firebase project that signs in your players.

Use the test-token panel to verify the configured project before putting the runtime key into a game build.

JavaScript SDK Sign-In

Exchange a Firebase ID token before saving.

TYPESCRIPT

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

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

const idToken = await getFirebaseIdTokenFromFirebaseAuth();
await PersistlyGameSaves.shared.signInWithFirebaseToken(idToken);

await PersistlyGameSaves.shared.saveData({
  level: 5,
  coins: 1200,
});

Unity SDK Sign-In

Use the Firebase token helper in Unity.

using Persistly.Unity;

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

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

await PersistlyGameSaves.Shared.SaveDataAsync(new PlayerData
{
    Level = 5,
    Coins = 1200,
});

Godot SDK Sign-In

Use the Firebase token helper in Godot.

GDSCRIPT

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 id_token := await get_firebase_id_token()
await persistly.sign_in_with_firebase_token(id_token)

persistly.save_data({
  "level": 5,
  "coins": 1200,
})

Saving

Saving after sign-in works the same way.

Auth Bridge changes how the account session is issued. It does not change the normal save model.

After sign-in, the SDK stores the Persistly account session locally and normal save helpers keep using that session.

saveData and saveSlot still write local data first. Cloud sync remains explicit through forceSyncData, forceSync, or due-sync helpers.

Normal save, load, and sync calls use the Persistly account session, not a Firebase token.

Sign Out

Sign-out behavior is local cleanup plus Firebase sign-out.

Keep logout explicit so one local player cannot inherit another player's cached save session.

Sign out of Firebase through the Firebase SDK so your game UI returns to a signed-out state.

Clear the local Persistly account/session/slot cache on that device so the next local player cannot read cached saves.

Phase 1A sign-out is local cleanup. It does not delete the remote Persistly account or revoke Firebase sessions.

Common Errors

Handle auth errors as player-safe recovery states.

auth_bridge_requires_paid_plan: the request used a Production runtime key from a Free workspace. Test with a Stage key or upgrade before production launch.

provider_not_configured: Firebase Auth is not configured for the Persistly environment selected by the runtime key.

provider_not_enabled: Firebase Auth is configured but disabled for this environment.

firebase_token_missing: the auth session request did not include a Firebase ID token.

firebase_token_expired: the Firebase ID token expired. Refresh it with Firebase and retry.

firebase_project_mismatch: the token belongs to a different Firebase project than the one configured in Persistly.

firebase_token_invalid: the token is malformed, cannot be verified, or is missing required Firebase claims.

account_auth_conflict: this Firebase identity is already linked to another Persistly account. Show recovery UI instead of merging silently.

Security Notes

Keep tokens out of logs and normal save routes.

Never log Firebase ID tokens, Persistly account session tokens, or full auth responses.

Use Stage runtime keys for development and Production runtime keys only in production builds.

Do not store the Firebase token as the save identity. Store the Persistly accountId and accountSessionToken through the SDK's normal local storage path.

Treat sign-out as a local Persistly cache purge plus a Firebase sign-out in your game.

Continue with account mode and direct API details.

Account modes

Use authRequired for Firebase Auth Bridge and keep anonymousFirst for no-auth games.

Direct API example

Advanced Firebase token exchange request for custom engines and SDK authors.