One User, Three Identities: The actingAs Pattern That Scaled With Every Feature

The problem arrives with organizations

Picture a product that starts simple: one auth account, one profile, one owner on everything. Then it grows the features every product grows. Users want an alternate profile — a different public face for a different context. Organizations arrive, and a user who manages one needs to create and publish as the organization, not as themselves.

Now one human, in one session, creates something under their own name in the morning and publishes under the organization in the afternoon. The organization's content must never go out under their personal profile, and their personal activity must never leak onto the organization's page.

The dangerous way to support this is ambient state: a "current profile" the app holds somewhere, with every endpoint assuming the auth uid is the actor. That works until the first feature where it doesn't — and by then "who is performing this action" is wired as "who is logged in" across every endpoint you own. Retrofitting the distinction means touching all of them.

The pattern, and the whole article, is one decision made early: "who is acting" is never ambient. It's a parameter — on every single call.

Three identity types, one string format

Make every identity a string id, and make the id itself say what it is:

The underscore encoding looks like a hack and is actually the design. An alternate profile's id contains its owner. Which means two of the three permission checks never touch the database:

• Acting as your primary profile? The id equals your auth uid. String comparison.
• Acting as an alternate? Extract the prefix, compare to your auth uid. String comparison.
• Acting as an organization? The one case that earns a lookup — is this user on the organization's access list, with a role that allows this?

Identity checks run on every authenticated request, so a hot path of two string comparisons and only occasionally a read isn't a micro-optimization — it's what makes checking everywhere affordable, which is what makes checking everywhere happen.

Wrap the format in helpers from day one so nobody parses strings by hand: an inferIdentityType(id) that says which of the three it is, an extractPrimaryUid(id) that pulls the owner out of an alternate. If the format ever changes, it changes in one file.

One parameter, injected once, verified once

The pattern has three parts, each living in exactly one place.

The frontend injects it. Every API wrapper passes actingAs automatically, read from a single selector that knows the active profile. Screens don't pass it — they can't forget it. When the user switches profiles, the selector changes, and every subsequent call acts as the new identity. No component is involved; no screen needs to know which identity is active, because the wrapper always does.

The backend verifies it. Every handler resolves the acting identity the same way:

async function handler(request, auth) {
  const actingAs = request.actingAs || auth.uid // default: yourself
 
  const permCheck = await canUserActAsIdentity(auth.uid, actingAs)
  if (!permCheck.allowed) {
    throw new AuthError(permCheck.reason)
  }
 
  // from here down, `actingAs` IS the caller.
  // auth.uid should not appear again.
}

Everything downstream keys on actingAs, never on the auth uid. This is the rule that takes discipline, because the auth uid is right there and usually works — for the primary-profile case, which is the case every test covers. The classic bug looks like this:

// Wrong — pins the query to the auth account, not the acting identity
.where("ownerId", "==", auth.uid)
 
// Right — the identity owns things; the account only proves access to identities
.where("ownerId", "==", actingAs)

Write the wrong version and the organization's content shows up while the user is browsing as themselves — and vanishes when they switch to the organization. The bug report says "things randomly disappear." It's never random. It's one query keyed on the wrong concept.

The payoff arrives with every later feature

The reason this pattern earns an article is what happens after it exists. Features built years later inherit multi-identity support without asking for it:

• API keys belong to identities. Mint a key while acting as the organization and the key sees the organization's data — the key stores the identity it was created under, and the gateway resolves it like any other caller. "Org-scoped API keys" requires zero additional design.
• Sandboxes provision identities. A developer sandbox's throwaway owner and members are just identities with no privileges elsewhere. The sandbox never needs its own concept of a fake user.
• Third-party extensions see one id. An extension asks "who am I scoped to" and gets an identity id — personal or organization, same shape. Org-scoped extensions fall out of the identity model, not out of extension code.
• An AI assistant acts as the connected identity. When chat connects to the product, every tool call carries the identity the user authorized — the same actingAs resolution, one more caller.

That's the compounding return: every feature that asks "who is doing this?" has one answer to integrate with. In the other timeline, those four features each grow their own notion of "on behalf of," and you reconcile four permission systems forever.

The failure modes to expect

• The auth-uid bug, repeatedly. Covered above, and no architecture prevents it — only review culture and a lint-level allergy to the auth uid appearing below the permission check. The ergonomic default (actingAs || auth.uid) makes the primary case work when callers omit the parameter, which is convenient — and exactly why the bug hides so well.
• Manual string parsing. The moment the id format exists, someone will check id.includes("__") inline, and each copy is one refactor away from wrong. Treat the helpers as sacred so the format stays an implementation detail with exactly one implementation.
• Identity documents drifting. If display data lives per-identity, an update applied to one identity's documents but not a sibling's produces profiles that disagree about their own name. Route updates through one helper that knows every document an identity owns.

Steal this workflow

1. The day you add organizations — or better, before — decide that actions carry an identity, as one explicit parameter on everything. Ambient identity is a bug class shipped as architecture.
2. Encode type and ownership in the identity id. Permission checks that are string comparisons are checks you'll actually run everywhere.
3. Inject actingAs in one frontend wrapper; verify it in one backend helper; default it to the auth uid for ergonomics.
4. Below the check, ban the auth uid. Ownership keys on the identity.
5. Wrap the id format in helpers from day one.
6. When later features need "on whose behalf" — keys, sandboxes, extensions, AI — hand them the identity id and nothing else.

FAQ