User Management

Overview

The Refresh platform separates the concept of identity (how you log in) from user (who you are in the system). A single person can have multiple identities (work email, personal email) that all link to different internal user records. This design supports:

HRIS-provisioned work accounts
User-created personal accounts
Account linking for cross-company history
GDPR compliance with data portability
Privacy separation between work and personal data

Core Concepts

The Person Model

┌─────────────────────────────────────────────────────────────────┐
│                        THE PERSON (Taylor)                       │
├─────────────────────┬─────────────────────┬─────────────────────┤
│  users (personal)   │  users (work-acme)  │  users (work-newco) │
│  id: user-P         │  id: user-A         │  id: user-N         │
│  primary_user_id:   │  primary_user_id:   │  primary_user_id:   │
│  NULL (is primary)  │  user-P             │  user-P             │
├─────────────────────┼─────────────────────┼─────────────────────┤
│  user_identities:   │  user_identities:   │  user_identities:   │
│  [email protected]   │  [email protected]    │  [email protected]   │
│  (active)           │  (DELETED on leave) │  (active)           │
├─────────────────────┼─────────────────────┼─────────────────────┤
│  tenant_users:      │  tenant_users:      │  tenant_users:      │
│  (none)             │  acme (INACTIVE)    │  newco (ACTIVE)     │
├─────────────────────┼─────────────────────┼─────────────────────┤
│  DATA OWNED:        │  DATA OWNED:        │  DATA OWNED:        │
│  - therapy sessions │  - survey responses │  - survey responses │
│  - EAP usage        │  - backfill data    │  - backfill data    │
│  - personal reports │  - HRIS records     │  - HRIS records     │
└─────────────────────┴─────────────────────┴─────────────────────┘

Key Distinctions

Concept

What It Is

Where Stored

Identity

A way to authenticate (email + FusionAuth)

user_identities

User

An internal record for data ownership

users

Primary User

The "main" account (usually personal)

users.primary_user_id = NULL

Linked User

Work accounts linked to a primary

users.primary_user_id = <primary>

Why Multiple User Records?

User IDs are immutable references stored in:

S3 JSON files (backfill data)
Data warehouse tables
Audit logs
External integrations

Merging user records would break these references. Instead, we link users while preserving their original IDs.

Database Schema

users Table

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  primary_user_id UUID REFERENCES users(id),  -- NULL if this IS the primary
  name TEXT,
  timezone TEXT DEFAULT 'UTC',
  is_anonymized BOOLEAN NOT NULL DEFAULT FALSE,
  anonymized_at TIMESTAMPTZ,
  created_date TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_date TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Index for finding all linked users
CREATE INDEX idx_users_primary_user_id ON users(primary_user_id);

Key Fields:

Field

Purpose

primary_user_id

NULL = this is a primary account; otherwise points to primary

is_anonymized

GDPR deletion flag - PII removed but record kept for FK integrity

user_identities Table

CREATE TABLE user_identities (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  fusionauth_id UUID UNIQUE,           -- NULL until user authenticates
  email TEXT UNIQUE NOT NULL,          -- One identity per email
  type TEXT NOT NULL CHECK (type IN ('personal', 'work')),
  tenant_id UUID REFERENCES tenants(id),  -- NULL for personal, set for work
  is_primary BOOLEAN NOT NULL DEFAULT FALSE,  -- Primary login method
  created_date TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_date TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Indexes
CREATE INDEX idx_user_identities_user_id ON user_identities(user_id);
CREATE INDEX idx_user_identities_email ON user_identities(email);
CREATE INDEX idx_user_identities_fusionauth_id ON user_identities(fusionauth_id);

Key Fields:

Field

Purpose

fusionauth_id

NULL until user authenticates; set on first login

email

Unique across all identities

type

personal or work

tenant_id

Which tenant provisioned this identity (NULL for personal)

is_primary

User's preferred login method

User Lifecycle Flows

Flow 1: HRIS Creates Work Account

When a company onboards and HRIS sync runs:

1. HRIS sync detects new employee [email protected]
   ↓
2. Create users row:
   - id: user-A
   - primary_user_id: NULL (no link yet)
   - name: "Taylor Smith"
   ↓
3. Create user_identities row:
   - user_id: user-A
   - fusionauth_id: NULL (not yet authenticated)
   - email: [email protected]
   - type: 'work'
   - tenant_id: acme-id
   ↓
4. Create tenant_users row:
   - tenant_id: acme-id
   - user_id: user-A
   - role: 'member'
   - status: 'active'

At this point:

User exists in your system but hasn't logged in
FusionAuth doesn't know about them yet
They'll be linked on first authentication

Flow 2: User Authenticates with Work Email

When the user logs in for the first time:

1. User clicks "Sign in" → redirected to FusionAuth
   ↓
2. FusionAuth self-registration creates account for [email protected]
   ↓
3. FusionAuth returns JWT with:
   - sub: fa-12345 (FusionAuth user ID)
   - email: [email protected]
   ↓
4. Your callback:
   - Lookup user_identities WHERE email = '[email protected]'
   - Found! fusionauth_id is NULL
   - Update: SET fusionauth_id = 'fa-12345'
   ↓
5. User is now linked and can access Acme tenant

Flow 3: User Creates Personal Account

When a user signs up with a personal email:

1. User clicks "Sign in with Google" using [email protected]
   ↓
2. FusionAuth SSO creates account (self-registration)
   ↓
3. FusionAuth returns JWT with:
   - sub: fa-67890
   - email: [email protected]
   ↓
4. Your callback:
   - Lookup user_identities WHERE LOWER(email) = '[email protected]'
   - Not found!
   - Create new users row:
     - id: user-P
     - primary_user_id: NULL (this is a primary account)
   - Create new user_identities row:
     - user_id: user-P
     - fusionauth_id: fa-67890
     - email: [email protected] (normalized to lowercase)
     - type: 'personal'
     - tenant_id: NULL
     - is_primary: TRUE
   ↓
5. User has personal account with no tenant access

Personal Account Without Tenant Access

Users with only a personal account (no linked work accounts) see a limited experience:

┌─────────────────────────────────────────────────┐
│  Welcome to Refresh                              │
├─────────────────────────────────────────────────┤
│                                                 │
│  You don't have access to any organization yet. │
│                                                 │
│  Options:                                       │
│  ─────────                                      │
│  • If your employer uses Refresh, sign in with  │
│    your work email to access your resources     │
│                                                 │
│  • Ask your employer to sign up for Refresh     │
│    at refresh.tech/employers                    │
│                                                 │
│  [Link Work Account]  [Learn More]              │
│                                                 │
└─────────────────────────────────────────────────┘

Future Enhancement: Personal accounts may gain access to user-specific resources and memberships independent of employer tenants.

Flow 4: Linking Personal to Work Account

Account linking is user-initiated. The system does not automatically detect that a personal account holder has a work account—this is the user's responsibility based on employer instructions.

Two linking directions:

Work → Personal: User logs in with work email, then links to personal account
Personal → Work: User logs in with personal email, provides work email for verification

Flow A: Work user links to personal account
─────────────────────────────────────────────
1. User logged in with [email protected] (user-A, work)
   ↓
2. Goes to Settings → "Link Personal Account"
   ↓
3. Enters [email protected]
   ↓
4. System sends verification code to [email protected]
   ↓
5. User enters code received at personal email
   ↓
6. On verification success:
   - If personal account exists (user-P):
     - Update users (user-A): SET primary_user_id = user-P
   - If personal account doesn't exist:
     - Create user-P as primary
     - Update users (user-A): SET primary_user_id = user-P
   ↓
7. Now user-A is linked to user-P

Flow B: Personal user links to work account
─────────────────────────────────────────────
1. User logged in with [email protected] (user-P, personal)
   ↓
2. Goes to Settings → "Link Work Account"
   ↓
3. Enters [email protected]
   ↓
4. System checks:
   - user_identities exists for [email protected]?
   ↓
5. If work identity exists (user-A):
   - Send verification code to [email protected]
   - User enters code to prove ownership
   - Update users (user-A): SET primary_user_id = user-P
   ↓
   If work identity doesn't exist:
   - Show message: "No account found for this email.
     Your employer may need to provision your account first."
   ↓
6. Now user-A is linked to user-P
   - Both user IDs still exist (no data loss)
   - Personal account (user-P) becomes the primary
   - All work accounts point to user-P via primary_user_id

Key Points:

The personal account is always the primary (owns the data lifecycle)
Work accounts become children of the personal account
This maintains a clean tree structure: one primary with many linked work accounts
is_primary field on user_identities indicates the user's preferred login method

Flow 5: Employee Leaves Company

When HRIS sync shows termination:

1. HRIS sync detects [email protected] terminated
   ↓
2. Update tenant_users:
   - SET status = 'inactive'
   ↓
3. Delete user_identities row for [email protected]
   ↓
4. Delete FusionAuth user for [email protected]
   ↓
5. Result:
   - users record (user-A) still exists (data preserved)
   - tenant_users record exists but inactive
   - User can't authenticate with work email
   - If linked to personal account, personal still works

Access After Termination

If user has personal account linked:

Can still log in with personal email
Can access personal data (therapy sessions, anonymous reports)
Cannot access terminated tenant's data
Can still access other active tenant memberships

If user only has work identity (no personal account):

Cannot log in at all
Loses all access to the system
Data is retained but inaccessible to the user

Future Enhancement: Terminated users without personal accounts may be offered a paid personal subscription to retain access to their data and history.

Flow 6: User Joins New Company

When a user's new employer also uses the platform:

1. NewCorp onboards, HRIS sync creates [email protected]
   - New users row: user-N
   - New user_identities row (fusionauth_id: NULL)
   - New tenant_users row for NewCorp
   ↓
2. Taylor logs in with [email protected]
   - Identity linked to user-N
   ↓
3. Taylor sees "Link to existing account?" prompt
   (If they have personal account [email protected])
   ↓
4. If Taylor chooses to link:
   - Update users (user-N): SET primary_user_id = user-P
   - Now user-P (personal), user-A (Acme), user-N (NewCorp) are all linked

When a user requests data deletion, the system performs a cascading de-identification across all linked accounts.

Legal Context: De-identified data that can never be mapped back to an individual may be retained. All personally identifiable information (PII) must be deleted.

1. User requests deletion (via personal account or email)
   ↓
2. Find all linked users:
   - user-P (primary)
   - user-A (Acme work)
   - user-N (NewCorp work)
   ↓
3. For EACH linked user (work accounts first, then personal):
   ↓
   3a. Delete PII from associated data:
       - Names, emails, gender, demographics
       - Any field that could identify the person
   ↓
   3b. Delete user_identities row for this user
   ↓
   3c. Delete corresponding FusionAuth user
   ↓
   3d. Update users record:
       - SET is_anonymized = TRUE
       - SET anonymized_at = NOW()
       - SET name = NULL
       - SET primary_user_id = NULL (unlink)
   ↓
4. Delete user_private records for all linked users
   ↓
5. Result:
   - user_id references in S3/warehouse still valid (FK integrity)
   - Derived/aggregated data retained (de-identified)
   - Person is completely unidentifiable
   - Cannot authenticate with any previous identity

Data Retention After Deletion

Data Type

Action

Reason

PII (name, email, gender, demographics)

Deleted

Required by GDPR

user_identities rows

Deleted

Contains email (PII)

FusionAuth users

Deleted

Contains auth credentials

users record

Anonymized

Preserved for FK integrity

Survey responses (anonymized)

Retained

De-identified aggregate data

Derived analytics

Retained

Cannot be traced to individual

Deletion Scope

The deletion cascades to all linked accounts:

┌─────────────────────────────────────────────────────────────────┐
│  GDPR Deletion Request for user-P (primary)                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Affected accounts:                                              │
│  ├── user-P (personal) ─────────── Anonymized                    │
│  ├── user-A (Acme work) ────────── Anonymized                    │
│  └── user-N (NewCorp work) ─────── Anonymized                    │
│                                                                  │
│  All identities deleted, all PII removed                         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Important: Users cannot selectively delete only their personal account while retaining work accounts. Deletion affects the entire identity graph.

Querying Linked Users

Helper Functions

/**
 * Get the primary user ID for any user
 * Returns the user's own ID if they are the primary
 */
async function getPrimaryUserId(db: DB, userId: string): Promise<string> {
	const user = await db.query.users.findFirst({
		where: eq(users.id, userId)
	});
	return user?.primaryUserId ?? userId;
}

/**
 * Get all user IDs for a person (primary + all linked)
 */
async function getAllLinkedUserIds(db: DB, userId: string): Promise<string[]> {
	const primaryId = await getPrimaryUserId(db, userId);

	const linkedUsers = await db.query.users.findMany({
		where: eq(users.primaryUserId, primaryId)
	});

	return [primaryId, ...linkedUsers.map((u) => u.id)];
}

/**
 * Get the work user_id for a specific tenant
 * Used when :tenantId is in the URL path
 */
async function getWorkUserIdForTenant(
	db: DB,
	userId: string,
	tenantId: string
): Promise<string | null> {
	const allUserIds = await getAllLinkedUserIds(db, userId);

	const tenantUser = await db.query.tenantUsers.findFirst({
		where: and(
			inArray(tenantUsers.userId, allUserIds),
			eq(tenantUsers.tenantId, tenantId),
			eq(tenantUsers.status, 'active')
		)
	});

	return tenantUser?.userId ?? null;
}

/**
 * Get the personal (primary) user_id
 * Used for personal routes
 */
async function getPersonalUserId(db: DB, userId: string): Promise<string> {
	return getPrimaryUserId(db, userId);
}

Query Patterns

Get all data for a person across all their accounts:

WITH person_users AS (
  -- Get primary
  SELECT id FROM users WHERE id = :userId
  UNION
  -- Get all linked to this user's primary
  SELECT id FROM users WHERE primary_user_id = (
    SELECT COALESCE(primary_user_id, id) FROM users WHERE id = :userId
  )
  UNION
  -- If this user IS a primary, get users linked to it
  SELECT id FROM users WHERE primary_user_id = :userId
)
SELECT * FROM survey_responses WHERE user_id IN (SELECT id FROM person_users);

Get data for a specific tenant context:

-- URL path contains :tenantId = 'newcorp-id'
-- Logged in user is 'user-P' (personal)

SELECT * FROM survey_responses
WHERE user_id = (
  SELECT tu.user_id
  FROM tenant_users tu
  JOIN users u ON u.id = tu.user_id
  WHERE tu.tenant_id = 'newcorp-id'
    AND tu.status = 'active'
    AND (u.id = 'user-P' OR u.primary_user_id = 'user-P')
);

Personal vs Work Data

Data Ownership Model

Data Type

Owned By

Example

Survey responses

Work user_id

Responses to company surveys

HRIS data

Work user_id

Job title, department, manager

Backfill data

Work user_id

Historical data from integrations

Therapy sessions

Personal user_id

EAP provider usage

Personal resources

Personal user_id

Wellness resources accessed

Anonymous reports

Personal user_id

Workplace concern reports

Account settings

Primary user_id

Timezone, preferences

Privacy Boundary

Tenant admins can see (for their employees):

Survey responses (aggregated or individual per survey settings)
Training completions
Resource usage (aggregated counts)

Tenant admins CANNOT see:

Personal account data
Anonymous reports content
EAP/therapy usage details
Data from other tenants

Route-Based Data Access

// Personal route - use primary user_id
// GET /personal/resources
async function getPersonalResources({ locals }) {
	const userId = await getPersonalUserId(db, locals.userId);
	return db.query.personalResources.findMany({
		where: eq(personalResources.userId, userId)
	});
}

// Tenant route - use work user_id for that tenant
// GET /tenants/:tenantId/surveys
async function getSurveys({ locals, params }) {
	const workUserId = await getWorkUserIdForTenant(
		db,
		locals.userId,
		params.tenantId // From URL path
	);
	return db.query.surveyResponses.findMany({
		where: eq(surveyResponses.userId, workUserId)
	});
}

Identity Resolution Flow

Complete flow when a request arrives:

async function resolveRequestContext(request: Request): Promise<RequestContext> {
	// 1. Validate FusionAuth JWT
	const jwt = await validateFusionAuthJwt(request.headers.get('Authorization'));

	// 2. Resolve to internal identity
	const identity = await resolveIdentity(jwt);

	// 3. Get logged-in user
	const loggedInUserId = identity.userId;

	// 4. Determine route type and resolve appropriate user_id
	const tenantId = request.params.tenant_id; // From URL path

	if (isPersonalRoute(request.url)) {
		// Personal route - use primary user
		const personalUserId = await getPersonalUserId(db, loggedInUserId);
		return {
			userId: personalUserId,
			tenantId: null,
			context: 'personal'
		};
	}

	if (!tenantId) {
		throw new Error('Tenant ID required in URL path for tenant routes');
	}

	// Bypass users can access any tenant without membership
	if (identity.hasAnyBypass) {
		return {
			userId: loggedInUserId,
			tenantId,
			context: 'tenant',
			canBypassRls: true
		};
	}

	// Tenant route - find work user for this tenant via membership
	const workUserId = await getWorkUserIdForTenant(db, loggedInUserId, tenantId);

	if (!workUserId) {
		throw new Error('User does not have access to this tenant');
	}

	return {
		userId: workUserId,
		tenantId,
		context: 'tenant',
		canBypassRls: false
	};
}

Account Linking UI

Settings Page

Users can manage their linked accounts from settings:

┌─────────────────────────────────────────────────┐
│  Account Settings                               │
├─────────────────────────────────────────────────┤
│                                                 │
│  Linked Accounts                                │
│  ─────────────────                              │
│                                                 │
│  ✓ [email protected] (Personal - Primary)        │
│    └─ This is your main account                │
│                                                 │
│  ✓ [email protected] (Work - Acme Corp)          │
│    └─ Inactive since Oct 2024                  │
│                                                 │
│  ✓ [email protected] (Work - NewCorp Inc)     │
│    └─ Active                                   │
│                                                 │
│  [+ Link Another Account]                       │
│                                                 │
└─────────────────────────────────────────────────┘

Linking Flow UI

┌─────────────────────────────────────────────────┐
│  Link Work Account                              │
├─────────────────────────────────────────────────┤
│                                                 │
│  Enter your work email address:                 │
│  ┌─────────────────────────────────────────┐   │
│  │ [email protected]                      │   │
│  └─────────────────────────────────────────┘   │
│                                                 │
│  [Verify & Link]                                │
│                                                 │
│  ─────────────────────────────────────────────  │
│  Why link accounts?                             │
│  • Access work resources from personal device   │
│  • Keep your history when changing jobs         │
│  • Manage all accounts from one place           │
│                                                 │
└─────────────────────────────────────────────────┘

Notification Routing

Notifications are sent to the appropriate email based on context. There is no dedicated notification_email field on the users table—instead, routing is determined by the identity associated with the action.

Routing Logic

/**
 * Get the email address for sending notifications
 * Routes based on context: work notifications → work email, personal → personal email
 */
async function getNotificationEmail(
	db: DB,
	userId: string,
	context: 'work' | 'personal',
	tenantId?: string
): Promise<string | null> {
	if (context === 'work' && tenantId) {
		// 1. Find work identity for this tenant
		const workIdentity = await db.query.userIdentities.findFirst({
			where: and(
				eq(userIdentities.userId, userId),
				eq(userIdentities.tenantId, tenantId),
				eq(userIdentities.type, 'work')
			)
		});

		if (workIdentity) {
			return workIdentity.email;
		}

		// 2. Fallback: Find any work identity for this user
		const anyWorkIdentity = await db.query.userIdentities.findFirst({
			where: and(eq(userIdentities.userId, userId), eq(userIdentities.type, 'work'))
		});

		if (anyWorkIdentity) {
			return anyWorkIdentity.email;
		}
	}

	if (context === 'personal') {
		// 1. Find personal identity
		const personalIdentity = await db.query.userIdentities.findFirst({
			where: and(eq(userIdentities.userId, userId), eq(userIdentities.type, 'personal'))
		});

		if (personalIdentity) {
			return personalIdentity.email;
		}
	}

	// 3. Fallback: Find primary identity for this user
	const primaryIdentity = await db.query.userIdentities.findFirst({
		where: and(eq(userIdentities.userId, userId), eq(userIdentities.isPrimary, true))
	});

	if (primaryIdentity) {
		return primaryIdentity.email;
	}

	// 4. Last resort: Any identity
	const anyIdentity = await db.query.userIdentities.findFirst({
		where: eq(userIdentities.userId, userId)
	});

	return anyIdentity?.email ?? null;
}

Notification Context Examples

Notification Type

Context

Email Used

Survey reminder

work

Work email for that tenant

HRIS sync complete

work

Work email for that tenant

New team member

work

Work email for that tenant

Therapy session reminder

personal

Personal email

Anonymous report update

personal

Personal email

Account security alert

personal

Primary identity email

Password reset

(auth)

Identity email used to log in

Why Not a Dedicated Field?

Context-aware routing - Work notifications should go to work email, personal to personal
No synchronization issues - Email always comes from the identity source of truth
Privacy separation - Ensures work-related notifications don't leak to personal email
Simpler data model - One less field to maintain and keep in sync

Best Practices

For HRIS Sync

Always create user_identities first - The identity links email to user
Set tenant_id on work identities - Tracks which tenant provisioned the identity
Leave fusionauth_id NULL - It gets set on first authentication
Check for existing identities - Avoid duplicates

For Authentication

Resolve by fusionauth_id first - Most efficient lookup
Fall back to email lookup - For first-time authentication
Create personal account if no match - Self-registration flow
Never delete user records - Only anonymize

For Data Queries

Always use the correct user_id - Personal vs work context matters
Use helper functions - getWorkUserIdForTenant, getPersonalUserId
Consider linked accounts - When showing "all my data"
Respect privacy boundaries - Personal data is personal

For Notifications

Always specify context - work or personal determines routing
Include tenantId for work context - Ensures correct work email is used
Handle missing identities gracefully - Fallback chain ensures delivery
Never hardcode email addresses - Always resolve from identities

Future Improvements

Structured Name Fields in Employee Data

Currently, name and email are stored on the users table and are user-controlled. For HRIS integrations, we should add structured name fields to employee_data:

first_name - Structured first name from HRIS
middle_name - Optional middle name
last_name - Structured last name from HRIS
display_name - Full/display name when HRIS only provides combined name
preferred_name - Nickname or preferred name (e.g., "Mike" instead of "Michael")

This would allow:

users.name and users.email remain user-controlled (their account/login identity)
employee_data name fields are tenant/HRIS-controlled (organizational directory)
UI displays with fallback logic: preferredName → firstName → displayName → users.name

This separation ensures users control their authentication identity while organizations can maintain their own employee records.

Authentication Flow - JWT and FusionAuth setup
Authorization - Roles and permissions
Multi-Tenancy - Tenant isolation
Developer Authentication Guide - Implementation details

Last updated: December 2025

PreviousAuthentication Flow NextAuthorization

Last updated 1 month ago

hashtagOverview

hashtagCore Concepts

hashtagThe Person Model

hashtagKey Distinctions

hashtagWhy Multiple User Records?

hashtagDatabase Schema

hashtagusers Table

hashtaguser_identities Table

hashtagUser Lifecycle Flows

hashtagFlow 1: HRIS Creates Work Account

hashtagFlow 2: User Authenticates with Work Email

hashtagFlow 3: User Creates Personal Account

hashtagPersonal Account Without Tenant Access

hashtagFlow 4: Linking Personal to Work Account

hashtagFlow 5: Employee Leaves Company

hashtagAccess After Termination

hashtagFlow 6: User Joins New Company

hashtagFlow 7: GDPR Deletion Request

hashtagData Retention After Deletion

hashtagDeletion Scope

hashtagQuerying Linked Users

hashtagHelper Functions

hashtagQuery Patterns

hashtagPersonal vs Work Data

hashtagData Ownership Model

hashtagPrivacy Boundary

hashtagRoute-Based Data Access

hashtagIdentity Resolution Flow

hashtagAccount Linking UI

hashtagSettings Page

hashtagLinking Flow UI

hashtagNotification Routing

hashtagRouting Logic

hashtagNotification Context Examples

hashtagWhy Not a Dedicated Field?

hashtagBest Practices

hashtagFor HRIS Sync

hashtagFor Authentication

hashtagFor Data Queries

hashtagFor Notifications

hashtagFuture Improvements

hashtagStructured Name Fields in Employee Data

hashtagRelated Documentation

Overview

Core Concepts

The Person Model

Key Distinctions

Why Multiple User Records?

Database Schema

users Table

user_identities Table

User Lifecycle Flows

Flow 1: HRIS Creates Work Account

Flow 2: User Authenticates with Work Email

Flow 3: User Creates Personal Account

Personal Account Without Tenant Access

Flow 4: Linking Personal to Work Account

Flow 5: Employee Leaves Company

Access After Termination

Flow 6: User Joins New Company

Flow 7: GDPR Deletion Request

Data Retention After Deletion

Deletion Scope

Querying Linked Users

Helper Functions

Query Patterns

Personal vs Work Data

Data Ownership Model

Privacy Boundary

Route-Based Data Access

Identity Resolution Flow

Account Linking UI

Settings Page

Linking Flow UI

Notification Routing

Routing Logic

Notification Context Examples

Why Not a Dedicated Field?

Best Practices

For HRIS Sync

For Authentication

For Data Queries

For Notifications

Future Improvements

Structured Name Fields in Employee Data

Related Documentation