multi-tenant-auth-referencelisted

# Multi-tenant auth and tenancy reference Auth bugs in a multi-tenant system are expensive to debug by guessing, because the failure modes look identical from the outside (a 401, a blank page, a row that "should" be there) but have completely different root causes. The fix is to maintain a ground-truth reference for your own system's token/role model instead of re-deriving it from scratch every time, and to never guess which token or role kind is in play. ## Document every token/credential kind as a table, not prose If your system mints more than one kind of credential (a full user session, a scoped short-lived token, a share link, an account-level token distinct from a session token), keep one table: what claims discriminate it, what mints it, what verifies it, and its TTL. The single highest-cost mistake in this space is guessing which kind of token a code path expects instead of looking it up. Treat two wrong guesses in one session as a sign the reference is missing or stale, not a sign to guess harder. If tokens are stored client-side across multiple keys (a global session token, a per-resource token, an account-level token that must never get swapped into the global slot), document the full key set and both directions of any swap that can happen. The classic bug here is exactly that: an unrelated code path swaps the global slot back to the wrong credential mid-flow, and everything downstream 401s in a way that looks unrelated to the actual cause. ## Build a symptom