Firebase UID versus your database user ID: define the identity mapping contract

Keep a verified Firebase subject distinct from the application's database user ID. Verify the token first, resolve the subject through an explicit account mapping and use the resulting internal identity for product relationships. A missing profile is an account-state problem, not permission to substitute the external UID into every UUID column or create a new account on each cache miss.

Establish the mapping key

For a synthetic product, define an external identity by trusted provider or project plus verified subject. Map that key to an internal profile ID with a uniqueness rule appropriate to the account model. Decide whether account creation happens automatically, through an invitation or through an explicit onboarding transaction. Email can change and may have provider-specific verification semantics, so do not silently use it as a universal substitute for the verified subject.

Firebase's ID-token guidance describes verification and the resulting UID. It establishes external identity only after signature and claim checks. It does not define the internal application schema, tenant membership or account-linking policy. Those are domain contracts that the backend must enforce independently of a successful Firebase sign-in.

Firebase: verified ID tokens and external user identity

A repeat-sign-in trace

Suppose the verified fixture subject firebase-user-A maps to internal UUID 00000000-0000-0000-0000-000000000001. On first access, the approved provisioning flow creates that association. On repeat access, a cache miss triggers a database lookup and returns the same UUID. A cache failure should not be interpreted as proof that the account is absent. Distinguish cache miss, mapping absent and database unavailable in both code and diagnostics.

The values are synthetic and the trace is not an executed Firebase integration. Keep the internal ID stable across token refresh and ordinary sign-in. If two simultaneous first requests can provision an account, enforce the external-identity uniqueness rule in the database and handle the conflict deterministically. An application-only exists check can race and produce duplicate profiles or inconsistent relationships.

Proposed identity resolution
verified (provider, subject)
  -> cache lookup with provider-scoped key
  -> authoritative mapping lookup on miss
  -> explicit linked / unlinked / unavailable state
  -> internal user ID for membership and record authorization

Cache the relationship without inventing authority

A mapping cache must include the trusted identity namespace and have an invalidation policy for linking, deletion or administrative correction. Do not cache an authorization decision forever alongside the ID mapping. A stable internal user ID can remain valid while workspace membership changes. Resolve or revalidate the access relationship at the boundary required by the operation, especially for queued exports and consequential writes.

Keep token validation cache, external-to-internal mapping cache and application data cache separate in reasoning and telemetry. A high cache hit rate says little about whether a removed member still has access. Conversely, a temporary mapping cache outage should not force a new identity. Operators need safe categories and correlation IDs, not raw ID tokens or complete profile records.

Account changes need a deliberate workflow

When supporting multiple sign-in providers, decide whether and how verified identities can link to one internal account. Require the appropriate proof and account-recovery policy; matching a display name or unverified email is not sufficient. For account deletion, record what happens to mappings, cached references and queued work. A later sign-in must follow the chosen recreation or recovery policy rather than silently attaching to stale relationships.

Before release, test repeat sign-in, cold cache, concurrent provisioning, unlinked subject, database outage and a removed membership using fictional accounts. Verify both the returned ID and the number of mapping/profile rows. No such account-level experiment was executed for this article. The inspected identity-resolution code supplies implementation context, while the worksheet defines the evidence needed to claim stable mapping behavior on a tested release.

Multi-tenant SaaS data isolation with FastAPI and PostgreSQL

Building UltraFit360: the app, coach portal and shared backend

Bring one API or data workflow and a sanitized failure example for a bounded implementation assessment.

AptixLabs saas development