Persistly verifies the Auth0 token signature through the tenant JWKS endpoint, then checks issuer, expiration, stable subject, and optional audience.
Auth0
Auth0 handles login. Persistly handles cloud-save sessions.
Auth Bridge is a short token exchange before normal save sync. Persistly verifies the Auth0 token and returns accountId plus accountSessionToken for save/load routes.
Phase 1CAuth0 ID tokenaccount sessions
Persistly Verification
What Persistly verifies
Persistly checks the Auth0 token against the environment configuration selected by the runtime key.
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 Auth0 tokens. They use the Persistly account session returned by Auth Bridge.
Auth0 client secrets, management API tokens, private keys, and provider secrets are never required by Persistly Auth Bridge.
Auth0 Responsibility
What Auth0 handles
Auth0 remains the player identity system and token issuer for your game.
Auth0 handles sign-in UI, credentials, password reset, social provider setup, sessions, and token issuance.
Your game decides when to ask the player to sign in and when to refresh the Auth0 token.
Persistly does not store Auth0 tokens, replace Auth0 user management, or revoke Auth0 sessions.
Dashboard Setup
Enable Auth0 per environment.
Stage and Production have separate settings so test users and production players can stay isolated.
01
Create or choose the Auth0 tenant your game already uses for player sign-in.
02
In the Persistly dashboard, open the project Authentication page and add Auth0 to Stage first.
03
Enter the Auth0 tenant domain such as your-tenant.us.auth0.com. Do not enter client secrets, management API tokens, private keys, or OAuth client secrets.
04
Leave audience empty when your game exchanges Auth0 ID tokens. Set audience only when your game sends Auth0 API access tokens and you want Persistly to enforce that audience.
05
Paste an Auth0 ID token or configured-audience access token into the dashboard test panel to verify Stage before using it in a game.
06
Use Free workspace Stage keys for testing. Upgrade before using Production Auth Bridge with live players.
07
Repeat the same review for Production only after the production build and Auth0 tenant settings are ready.
08
Use Auth0 in the game to obtain the signed-in player's ID token or access token.
09
Pass that 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 Auth0 Auth Bridge on Stage. Production Auth Bridge requires a paid workspace plan.
Use the Auth0 tenant domain from the tenant that signs in your players.
Set an audience only when your game sends Auth0 API access tokens. ID token flows usually do not need an audience setting.
Use the test-token panel to verify the configured tenant before putting the runtime key into a game build.
Auth0 Application URLs
Use your game URLs in Auth0, not Persistly URLs.
Persistly verifies tokens after your game signs the player in. The Auth0 application still belongs to your game.
Allowed Callback URLs should point to the game or app callback URL, not to a Persistly URL.
Allowed Web Origins should include the game or app origin that runs the Auth0 login flow.
Allowed Logout URLs should include the game or app logout or return origin.
Persistly stores the tenant domain and optional audience only for token verification. Your game still needs its Auth0 domain and client ID for login UI.
JavaScript SDK Sign-In
Exchange an Auth0 token before saving.
await PersistlyGameSaves.configure({
runtimeKey: "ps_test_replace_me",
accountMode: "authRequired",
});
const token = await getAuth0Token();
try {
await PersistlyGameSaves.shared.signInWithProvider({
provider: "auth0",
token,
deviceLabel: "web",
});
} catch (error) {
if (error && typeof error === "object" && "code" in error && error.code === "account_auth_conflict") {
showAccountConflictUI(error.details);
return;
}
throw error;
}Unity SDK Sign-In
Use the Auth0 token helper in Unity.
await PersistlyGameSaves.ConfigureAsync(new PersistlyGameSavesSettings("ps_test_replace_me")
{
AccountMode = PersistlyAccountMode.AuthRequired,
});
var token = await GetAuth0TokenAsync();
try
{
await PersistlyGameSaves.Shared.SignInWithProviderAsync(
new PersistlyProviderSignInRequest(PersistlyAuthProvider.Auth0, token)
{
DeviceLabel = "unity"
});
}
catch (PersistlyApiError error) when (error.Code == PersistlyErrorCode.AccountAuthConflict)
{
ShowAccountConflictUI(error.DetailsJson);
}Godot SDK Sign-In
Use the Auth0 token helper in Godot.
persistly.configure({
"runtime_key": "ps_test_replace_me",
"account_mode": "authRequired",
})
var token := await get_auth0_token()
var result := await persistly.sign_in_with_provider({
"provider": "auth0",
"token": token,
"deviceLabel": "godot",
})
if result.get("status") == "account_auth_conflict":
show_account_conflict_ui(result.get("error", {}))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 an Auth0 token.
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: Auth0 is not configured for the Persistly environment selected by the runtime key.
provider_not_enabled: Auth0 is configured but disabled for this environment.
auth0_domain_required: the Persistly environment is missing its Auth0 tenant domain.
auth0_domain_invalid: the configured Auth0 tenant domain is not valid.
auth0_token_missing: the auth session request did not include an Auth0 token.
auth0_token_expired: the Auth0 token expired. Refresh it with Auth0 and retry.
auth0_issuer_mismatch: the token issuer does not match the configured Auth0 tenant domain.
auth0_audience_mismatch: the token audience does not match the configured audience.
auth0_token_invalid: the token is malformed, cannot be verified, or is missing required claims.
account_auth_conflict: this Auth0 identity is already linked to a different Persistly account. Show recovery UI instead of merging silently.
Sign Out
Sign-out behavior is local cleanup plus Auth0 sign-out.
Keep logout explicit so one local player cannot inherit another player's cached save session.
Sign out of Auth0 through the Auth0 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.
Sign-out is local cleanup. It does not delete the remote Persistly account or revoke Auth0 sessions.
Security Notes
Keep tokens and Auth0 secrets out of logs.
Never log Auth0 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 paste Auth0 client secrets, management API tokens, private keys, or provider secrets into Persistly Auth Bridge configuration.
Do not store the Auth0 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 an Auth0 sign-out in your game.
Related
Continue with account mode and direct API details.
Use authRequired for Auth0 Auth Bridge and keep anonymousFirst for no-auth games.
Advanced provider-token exchange request for custom engines and SDK authors.