Firebase Auth Token Expired in Unity Session Resume - Refresh Flow and Clock Drift Fix

If players return from background and your Unity game suddenly reports token expired errors, the issue is usually not account state corruption. In most cases, the app resumes with stale auth state before refresh completes, or device time drift makes a still-valid session appear expired.

This fix path focuses on safe resume sequencing so gameplay APIs only run after auth state is fully valid again.

Problem summary

Common symptoms:

API calls fail right after app resume with token expired or unauthorized errors
session works during fresh launch but breaks after idle or device sleep
issue appears more often on unstable mobile networks
auth recovers only after full app restart

Impact:

players see forced relogin loops or blocked cloud-sync actions
resume reliability drops during live events and patch windows

Root causes

Resume race condition Gameplay services call backend endpoints before Firebase token refresh finishes.
Clock drift between device and token issuer Device time skew causes tokens to be treated as expired earlier than expected.
Missing offline-to-online auth recovery Cached auth state is reused without revalidation after reconnect.
Retry policy without auth-state awareness Generic retries keep replaying requests with an already invalid token.

Fix steps

Step 1 - Gate resume traffic behind auth revalidation

On app resume:

Pause outbound authenticated requests.
Force-check current Firebase user state.
Refresh token before resuming gameplay API traffic.

Do not treat resume as equivalent to cold start for auth-sensitive calls.

Step 2 - Implement explicit token refresh sequencing

Use a deterministic sequence:

Resume event fires.
Trigger token refresh.
Wait for success or failure callback.
Release request queue only on success.

If refresh fails, move to controlled reauth UI instead of silent retry loops.

Step 3 - Add clock drift tolerance checks

Compare trusted server timestamp against device timestamp periodically.
Flag significant drift in diagnostics.
If drift exceeds your threshold, run a fresh token validation pass before queued requests.

This reduces false-expiry behavior on misconfigured devices.

Step 4 - Harden offline and reconnect behavior

Detect connectivity restoration.
Refresh auth token once network is stable.
Replay queued operations only after token validity is confirmed.

Avoid replaying writes with stale bearer tokens.

Step 5 - Add auth-aware retry policy

For 401 or token-expired responses:

perform one refresh attempt first
retry request once with the new token
fail fast to reauth flow if refresh fails

This prevents high-noise retry storms that never recover.

Verification checklist

[ ] Resume path blocks authenticated API calls until token refresh completes.
[ ] Session resumes cleanly after idle, sleep, and background restore tests.
[ ] Clock drift diagnostics are logged and monitored for affected devices.
[ ] Offline-to-online reconnect path refreshes token before request replay.
[ ] 401 handling uses refresh-first logic and avoids infinite retries.

Alternative fixes

If only Android devices fail, validate lifecycle callbacks and background behavior differences in your Unity activity integration.
If only specific regions fail, inspect network transition timing and auth endpoint latency before lowering token-expiry assumptions.
If failures started after SDK updates, pin known-good Firebase package versions and retest resume sequence before upgrading again.

Prevention tips

Keep a resume smoke test in CI device runs that covers sleep, reconnect, and token refresh timing.
Track auth refresh latency and failure-rate metrics by app version.
Tie release readiness to resume-auth pass rates, not only cold-start login checks.

FAQ

Why does auth work on first launch but fail on resume

Cold start usually performs full initialization. Resume paths often skip parts of auth setup and can race request dispatch.

Should we force logout on every token-expired response

No. Try a single refresh-first recovery path. Forced logout should be fallback behavior after refresh failure.

Can device time really break token validation

Yes. Significant clock drift can invalidate expiry checks and trigger false token-expired handling.