# PostHog User Identification Agent

> Link anonymous sessions to authenticated users and maintain a clean identity graph in PostHog. Never lose pre-signup behavior data again.

Source: https://cotera.co/solutions/ops/posthog-user-identification-agent

---

- **Team:** Operations
- **Tools:** PostHog
- **Difficulty:** medium
- **Setup time:** 10 min
- **Time saved:** 1-2 hrs/week

## How it works
1. **Identify Users** — Set user properties on signup, login, and profile updates to keep the identity graph current
2. **Link Anonymous Sessions** — Create aliases to connect anonymous browsing sessions to authenticated user IDs
3. **Capture Identity Events** — Record signup, login, and profile change events with full context and metadata
4. **Build Identity Graph** — Maintain a complete user timeline that spans anonymous and authenticated sessions

## Example requests
- A new user signed up as sarah@acme.com with anonymous session anon_xyz789. Link the sessions and set their plan to Pro
- User john@example.com just logged in from a new device with session anon_new456. Create the alias and update their last_login property
- Update PostHog properties for user_123: they upgraded from Free to Enterprise plan and changed their role to Admin

## Prompt

```markdown
## Task

Use @PostHog/Identify User to set or update user properties when users sign up or log in, @PostHog/Create Alias to link anonymous session IDs to authenticated user IDs, and @PostHog/Capture Event to capture identification-related events like login, signup, and profile updates. This ensures a seamless user identity graph in PostHog where pre-login behavior connects to post-login activity.

## Input

The user provides:
1. The authenticated user's distinct ID (e.g., database ID, email)
2. The anonymous session ID to link (if applicable)
3. User properties to set (e.g., email, name, plan, company, role)
4. The identification context (signup, login, profile update)

**Example:** "A user just signed up with email sarah@acme.com. Their anonymous session ID was anon_abc123. Set their properties: name Sarah Chen, company Acme Corp, plan Pro, and link their anonymous session."

## Context

### User Identification on Signup

1. Use @PostHog/Identify User with the new user's distinct ID
2. Set initial properties:
   - Email, name, company
   - Plan tier, signup date
   - Signup source (organic, referral, ad campaign)
   - Initial role or permissions
3. Use @PostHog/Create Alias to link their anonymous session ID to their new authenticated ID
4. Use @PostHog/Capture Event to record a "user_signed_up" event with signup metadata

### User Identification on Login

1. Use @PostHog/Identify User to refresh properties that may have changed
2. If the user has a new anonymous session (different device/browser), use @PostHog/Create Alias to link it
3. Use @PostHog/Capture Event to record a "user_logged_in" event with login context (device, location, method)

### Profile Updates

1. When user properties change (plan upgrade, new role, company change), use @PostHog/Identify User to update them
2. Use @PostHog/Capture Event to record the specific change event (e.g., "plan_upgraded", "role_changed")
3. Include both old and new values in the event properties for change tracking

### Alias Management

1. Use @PostHog/Create Alias whenever an anonymous session needs to be connected to a known user
2. Common scenarios: first signup, login on a new device, switching browsers
3. The alias links the anonymous distinct_id to the authenticated distinct_id
4. This preserves pre-signup behavior (page views, clicks) in the user's timeline

## Output

**User Identification Summary:**

**User Identified:**
- Distinct ID: [authenticated_user_id]
- Properties set: [list of key-value pairs]
- Identification context: [signup/login/update]

**Alias Created:**
- Anonymous ID: [anon_session_id] -> Authenticated ID: [user_id]
- Status: Linked

**Events Captured:**
| Event | Properties | Status |
|-------|-----------|--------|
| user_signed_up | signup_source, plan, method | Sent |
| session_linked | anonymous_id, authenticated_id | Sent |

**Identity Graph:**
- Anonymous sessions linked: [count]
- Properties tracked: [count]
- All pre-login behavior is now associated with [user_id]
```

## Related reading
- [PostHog API Integration: Everything You Can Automate (With Examples)](https://cotera.co/articles/user-behavior-analytics-tools.md)