0
# Identity Management
1

2
Identity management functionality handles user identification across different stages of the user lifecycle. It enables linking anonymous users to identified users and merging user profiles when multiple identities refer to the same person.
3

4
## Capabilities
5

6
### User Aliasing
7

8
Create one-way mappings between user identifiers to associate anonymous sessions with identified users.
9

10
```python { .api }
11
def alias(alias_id: str, original: str, meta: dict = None):
12
    """
13
    Creates an alias which Mixpanel will use to remap one id to another.
14

15
    Parameters:
16
    - alias_id (str): A distinct_id to be merged with the original distinct_id. Each alias can only map to one distinct_id.
17
    - original (str): A distinct_id to be merged with alias_id.
18
    - meta (dict, optional): Overrides Mixpanel special properties
19

20
    Returns:
21
    None
22

23
    Note: This method always results in a synchronous HTTP request to Mixpanel servers, regardless of any custom consumer.
24
    """
25
```
26

27
**Usage Example:**
28

29
```python
30
from mixpanel import Mixpanel
31

32
mp = Mixpanel("YOUR_PROJECT_TOKEN")
33

34
# Link anonymous user to identified user after signup/login
35
# Anonymous user was tracked as "anonymous_12345"
36
# After signup, user gets permanent ID "user_67890"
37
mp.alias("user_67890", "anonymous_12345")
38

39
# Now all future events for "user_67890" will be associated with 
40
# the historical events from "anonymous_12345"
41
```
42

43
### Profile Merging
44

45
Merge two user profiles when they represent the same person, combining all historical data and properties.
46

47
```python { .api }
48
def merge(api_key: str, distinct_id1: str, distinct_id2: str, meta: dict = None, api_secret: str = None):
49
    """
50
    Merges the two given distinct_ids.
51

52
    Parameters:
53
    - api_key (str): (DEPRECATED) Your Mixpanel project's API key
54
    - distinct_id1 (str): The first distinct_id to merge
55
    - distinct_id2 (str): The second (other) distinct_id to merge
56
    - meta (dict, optional): Overrides Mixpanel special properties
57
    - api_secret (str, optional): Your Mixpanel project's API secret (recommended over api_key)
58

59
    Returns:
60
    None
61

62
    Note: The api_key parameter is deprecated. Use api_secret instead. This operation requires API credentials and combines all profile data from both identities.
63
    """
64
```
65

66
**Usage Example:**
67

68
```python
69
from mixpanel import Mixpanel
70

71
mp = Mixpanel("YOUR_PROJECT_TOKEN")
72

73
# Merge two user profiles that represent the same person
74
# This might happen when a user signs up with different methods
75
# (email vs social login) or when duplicate accounts are discovered
76
mp.merge(
77
    api_key="DEPRECATED_API_KEY",  # Will be removed in future versions
78
    api_secret="YOUR_API_SECRET",   # Recommended approach
79
    distinct_id1="user_email_123",
80
    distinct_id2="user_social_456"
81
)
82

83
# After merging, both IDs will reference the same combined profile
84
# All events and properties from both profiles are preserved
85
```
86

87
## Identity Management Workflows
88

89
### Anonymous to Identified User Flow
90

91
This is the most common identity management scenario where anonymous users become identified after registration or login.
92

93
```python
94
from mixpanel import Mixpanel
95
import uuid
96

97
mp = Mixpanel("YOUR_PROJECT_TOKEN")
98

99
# 1. Track anonymous user events
100
anonymous_id = str(uuid.uuid4())
101
mp.track(anonymous_id, "page_viewed", {"page": "homepage"})
102
mp.track(anonymous_id, "button_clicked", {"button": "signup"})
103

104
# 2. User signs up and gets a permanent ID
105
permanent_id = "user_12345"
106

107
# 3. Create alias to link anonymous behavior to permanent identity
108
mp.alias(permanent_id, anonymous_id)
109

110
# 4. Continue tracking with permanent ID
111
mp.track(permanent_id, "signup_completed", {"method": "email"})
112
mp.people_set(permanent_id, {
113
    "$first_name": "John",
114
    "$email": "john@example.com"
115
})
116
```
117

118
### Profile Consolidation
119

120
When duplicate profiles need to be merged into a single identity.
121

122
```python
123
from mixpanel import Mixpanel
124

125
mp = Mixpanel("YOUR_PROJECT_TOKEN")
126

127
# Scenario: User has two accounts that need to be consolidated
128
primary_id = "user_primary_123"
129
duplicate_id = "user_duplicate_456"
130

131
# Set properties on both profiles (simulating existing data)
132
mp.people_set(primary_id, {"plan": "premium", "signup_date": "2024-01-01"})
133
mp.people_set(duplicate_id, {"phone": "+1234567890", "verified": True})
134

135
# Merge the profiles - all data from both will be combined
136
mp.merge(
137
    api_secret="YOUR_API_SECRET",
138
    distinct_id1=primary_id,
139
    distinct_id2=duplicate_id
140
)
141

142
# Continue using either ID - they now reference the same profile
143
mp.track(primary_id, "profile_merged", {"merge_reason": "duplicate_cleanup"})
144
```
145

146
## Best Practices
147

148
### Alias Management
149

150
- Create aliases as soon as a user transitions from anonymous to identified
151
- Each alias should only map to one distinct_id to avoid confusion
152
- Use alias operations immediately after user registration or login events
153

154
### Profile Merging
155

156
- Always use the latest API secret instead of the deprecated API key
157
- Carefully plan merge operations as they combine all historical data
158
- Test merge operations in a development environment first
159
- Document which distinct_id should be considered the "primary" identity
160

161
### Identity Consistency
162

163
- Maintain consistent distinct_id formats throughout your application
164
- Implement proper error handling for identity operations
165
- Consider the impact on user analytics and segmentation when merging profiles
166

167
### Error Handling
168

169
Identity operations may fail due to network issues or API restrictions:
170

171
```python
172
from mixpanel import Mixpanel, MixpanelException
173

174
mp = Mixpanel("YOUR_PROJECT_TOKEN")
175

176
try:
177
    mp.alias("new_user_123", "anonymous_456")
178
except MixpanelException as e:
179
    print(f"Alias operation failed: {e}")
180
    # Implement retry logic or fallback handling
181

182
try:
183
    mp.merge(
184
        api_secret="YOUR_API_SECRET",
185
        distinct_id1="user_1",
186
        distinct_id2="user_2"
187
    )
188
except MixpanelException as e:
189
    print(f"Merge operation failed: {e}")
190
    # Handle merge failure appropriately
191
```
192

193
## Important Notes
194

195
### Synchronous Operations
196

197
- The `alias` method always makes synchronous HTTP requests regardless of the consumer configuration
198
- Plan for potential latency when calling alias in user-facing workflows
199
- Consider implementing alias operations asynchronously in background tasks
200

201
### API Requirements
202

203
- The `merge` operation requires API credentials (secret or key)
204
- Ensure proper credential management and security practices
205
- Monitor API usage as merge operations may have rate limits
206

207
### Data Implications
208

209
- Alias operations create permanent one-way mappings
210
- Merge operations combine all profile data and cannot be undone
211
- Plan identity management strategies carefully to avoid data conflicts