Multi-Tenant Identity Modeling for Event Analytics

Product and operational questions often use several identities at once: a person, account, workspace, session, request, device, or anonymous visitor. Treating those values as interchangeable creates inflated funnels, broken retention cohorts, and unsafe data exposure.

Define the grain and ownership of each identifier before using it in SQL.

Separate identity levels

Use distinct fields for distinct entities:

Field	Meaning	Example use
`account_id`	Stable customer or billing account	Revenue, plan, and account retention
`workspace_id`	Product workspace inside an account	Collaboration and workspace activity
`user_id`	Stable internal person identifier	User activation and feature adoption
`anonymous_id`	Pre-authentication browser or device identifier	Landing-to-signup attribution
`session_id`	Bounded interaction period	Journey and session analysis
`request_id`	One request or processing attempt	Operational correlation

Do not put an email address into user_id. Prefer internal pseudonymous identifiers and keep the identity lookup in the system that already owns personal data.

Define tenant boundaries

Every multi-tenant event should include the tenant identifier needed for authorization and analysis. Choose one canonical account-level field and use it consistently across services. If an event belongs to a workspace, include both account_id and workspace_id rather than overloading one field.

Decide how to represent internal traffic, test tenants, deleted tenants, and account merges. A dashboard that silently mixes production customers with employees and automated tests will produce misleading rates.

Link anonymous and authenticated activity carefully

An anonymous visitor may later become an authenticated user. Record the explicit link event only after the application establishes the relationship:

{
  "event_name": "identity_linked",
  "anonymous_id": "anon_7b2",
  "user_id": "usr_42",
  "account_id": "acct_18",
  "link_reason": "registration_completed",
  "identity_policy_version": "v2"
}

Do not rewrite historical events silently. Keep the link time and policy version so a query can distinguish what was known at event time from later identity resolution. Review consent and privacy requirements before connecting identifiers across contexts.

Choose the correct analytical grain

Count accounts for account activation and expansion. Count users for individual adoption. Count distinct sessions for session engagement. Count terminal workflow IDs for job or webhook outcomes.

State the grain in the metric definition:

“weekly active accounts” means distinct account_id values with an eligible core event;
“activated users” means distinct user_id values reaching the activation milestone;
“request failure rate” uses eligible request events, not distinct users.

The funnel and cohort retention guides explain how identity choice changes denominators.

Handle lifecycle changes

Account merges, user deletion, workspace transfer, and membership changes require explicit policy. Preserve immutable event-time identifiers when auditability matters, and join to a current dimension only when the question asks for current ownership.

For deletion requests, document which pseudonymous identifiers remain necessary, which can be irreversibly transformed, and which events must be removed. Follow data retention and deletion and sensitive-data redaction.

Validate with edge cases

Test one user in multiple workspaces, multiple users in one account, an anonymous-to-authenticated transition, an account merge, an employee tenant, and a deleted user. Confirm that activation, retention, and revenue queries count the intended entity exactly once.

Use this doc with your coding agent