0
# Account Management & Sharing
1
2
MyPlex account services for user authentication, server sharing, managed users, friend invitations, and cloud-based features like watchlists and content discovery.
3
4
## Capabilities
5
6
### MyPlexAccount Authentication
7
8
Primary interface for Plex.tv account services and authentication.
9
10
```python { .api }
11
class MyPlexAccount:
12
def __init__(self, username=None, password=None, token=None, session=None, timeout=None, code=None, remember=True):
13
"""
14
Authenticate with MyPlex (Plex.tv) account.
15
16
Args:
17
username (str, optional): Plex username or email
18
password (str, optional): Account password
19
token (str, optional): Authentication token
20
session (requests.Session, optional): HTTP session
21
timeout (int, optional): Request timeout
22
code (str, optional): Two-factor authentication code
23
remember (bool): Remember authentication token
24
"""
25
26
def signout(self):
27
"""Sign out of Plex account and invalidate tokens."""
28
29
def claimToken(self):
30
"""
31
Generate claim token for server setup.
32
33
Returns:
34
str: Claim token for new server registration
35
"""
36
37
def createToken(self):
38
"""
39
Create new authentication token.
40
41
Returns:
42
str: New authentication token
43
"""
44
```
45
46
### Server & Resource Access
47
48
Access Plex servers and resources associated with your account.
49
50
```python { .api }
51
class MyPlexAccount:
52
def resources(self):
53
"""
54
Get available Plex servers and resources.
55
56
Returns:
57
list: List of MyPlexResource objects
58
"""
59
60
def resource(self, name):
61
"""
62
Get specific server resource by name.
63
64
Args:
65
name (str): Server name to find
66
67
Returns:
68
MyPlexResource: Server resource object
69
70
Raises:
71
NotFound: If server with specified name is not found
72
"""
73
74
def devices(self):
75
"""
76
Get registered devices.
77
78
Returns:
79
list: List of MyPlexDevice objects
80
"""
81
82
def device(self, name=None, clientId=None):
83
"""
84
Get specific device.
85
86
Args:
87
name (str, optional): Device name
88
clientId (str, optional): Device client ID
89
90
Returns:
91
MyPlexDevice: Device object
92
"""
93
94
class MyPlexResource:
95
"""Plex server resource accessible through MyPlex."""
96
97
@property
98
def name(self):
99
"""str: Server name."""
100
101
@property
102
def product(self):
103
"""str: Server product type."""
104
105
@property
106
def owned(self):
107
"""bool: Whether you own this server."""
108
109
def connect(self, ssl=None, timeout=None):
110
"""
111
Connect to this server resource.
112
113
Args:
114
ssl (bool, optional): Force SSL connection
115
timeout (int, optional): Connection timeout
116
117
Returns:
118
PlexServer: Connected server instance
119
"""
120
121
class MyPlexDevice:
122
"""Registered Plex device."""
123
124
@property
125
def name(self):
126
"""str: Device name."""
127
128
@property
129
def product(self):
130
"""str: Device product type."""
131
132
@property
133
def clientIdentifier(self):
134
"""str: Unique device identifier."""
135
```
136
137
### User Management
138
139
Manage home users, friends, and sharing permissions.
140
141
```python { .api }
142
class MyPlexAccount:
143
def users(self):
144
"""
145
Get managed users and friends.
146
147
Returns:
148
list: List of MyPlexUser objects
149
"""
150
151
def user(self, username):
152
"""
153
Get specific user by username.
154
155
Args:
156
username (str): Username to find
157
158
Returns:
159
MyPlexUser: User object
160
"""
161
162
def createHomeUser(self, user, server, sections=None, allowSync=None, allowCameraUpload=None, allowChannelContent=None, **kwargs):
163
"""
164
Create managed home user.
165
166
Args:
167
user (str): Username for new managed user
168
server (PlexServer): Server to grant access to
169
sections (list, optional): Library sections to share
170
allowSync (bool, optional): Allow mobile sync
171
allowCameraUpload (bool, optional): Allow camera uploads
172
allowChannelContent (bool, optional): Allow channel content
173
**kwargs: Additional user settings
174
175
Returns:
176
MyPlexUser: Created user object
177
"""
178
179
def inviteFriend(self, user, server, sections=None, allowSync=None, allowCameraUpload=None, allowChannelContent=None, **kwargs):
180
"""
181
Invite friend to share server.
182
183
Args:
184
user (str): Email address to invite
185
server (PlexServer): Server to share
186
sections (list, optional): Library sections to share
187
allowSync (bool, optional): Allow mobile sync
188
allowCameraUpload (bool, optional): Allow camera uploads
189
allowChannelContent (bool, optional): Allow channel content
190
**kwargs: Additional sharing settings
191
192
Returns:
193
MyPlexInvite: Created invitation object
194
"""
195
196
def removeFriend(self, user):
197
"""
198
Remove friend access.
199
200
Args:
201
user (str or MyPlexUser): User to remove
202
"""
203
204
def removeHomeUser(self, user):
205
"""
206
Remove managed home user.
207
208
Args:
209
user (str or MyPlexUser): User to remove
210
"""
211
212
def switchHomeUser(self, user, pin=None):
213
"""
214
Switch to managed home user context.
215
216
Args:
217
user (str or MyPlexUser): User to switch to
218
pin (str, optional): User PIN if required
219
220
Returns:
221
MyPlexAccount: Account context for the managed user
222
"""
223
224
class MyPlexUser:
225
"""Plex user account (friend or managed user)."""
226
227
@property
228
def title(self):
229
"""str: User display name."""
230
231
@property
232
def username(self):
233
"""str: Username."""
234
235
@property
236
def email(self):
237
"""str: Email address."""
238
239
@property
240
def friend(self):
241
"""bool: Whether this is a friend (vs managed user)."""
242
243
@property
244
def home(self):
245
"""bool: Whether this is a home user."""
246
247
class MyPlexInvite:
248
"""User invitation for server sharing."""
249
250
@property
251
def email(self):
252
"""str: Invited email address."""
253
254
@property
255
def createdAt(self):
256
"""datetime: When invitation was sent."""
257
258
def delete(self):
259
"""Cancel this invitation."""
260
```
261
262
### Watchlist Management
263
264
Manage personal watchlist across all Plex services.
265
266
```python { .api }
267
class MyPlexAccount:
268
def watchlist(self, filter=None, sort=None, libtype=None, **kwargs):
269
"""
270
Get user watchlist items.
271
272
Args:
273
filter (str, optional): Filter criteria
274
sort (str, optional): Sort order
275
libtype (str, optional): Media type filter ('movie', 'show')
276
**kwargs: Additional filter parameters
277
278
Returns:
279
list: List of watchlist media objects
280
"""
281
282
def addToWatchlist(self, items):
283
"""
284
Add items to watchlist.
285
286
Args:
287
items (list or single item): Media items to add
288
"""
289
290
def removeFromWatchlist(self, items):
291
"""
292
Remove items from watchlist.
293
294
Args:
295
items (list or single item): Media items to remove
296
"""
297
298
def onWatchlist(self, item):
299
"""
300
Check if item is on watchlist.
301
302
Args:
303
item: Media item to check
304
305
Returns:
306
bool: True if item is on watchlist
307
"""
308
```
309
310
### Content Discovery
311
312
Discover new content through Plex's recommendation engine.
313
314
```python { .api }
315
class MyPlexAccount:
316
def searchDiscover(self, query, limit=30, libtype=None, **kwargs):
317
"""
318
Search Plex content discovery.
319
320
Args:
321
query (str): Search query
322
limit (int): Maximum results to return
323
libtype (str, optional): Media type ('movie', 'show', 'artist')
324
**kwargs: Additional search parameters
325
326
Returns:
327
list: List of discovered content items
328
"""
329
```
330
331
### Sync & History
332
333
Access mobile sync items and account playback history.
334
335
```python { .api }
336
class MyPlexAccount:
337
def syncItems(self, client=None, clientId=None):
338
"""
339
Get items available for mobile sync.
340
341
Args:
342
client (str, optional): Client name filter
343
clientId (str, optional): Client ID filter
344
345
Returns:
346
list: List of SyncItem objects
347
"""
348
349
def history(self, maxresults=None, mindate=None):
350
"""
351
Get account playback history.
352
353
Args:
354
maxresults (int, optional): Maximum results to return
355
mindate (datetime, optional): Earliest date to include
356
357
Returns:
358
list: List of historical playback records
359
"""
360
361
def viewStateSync(self):
362
"""
363
Get view state synchronization status.
364
365
Returns:
366
dict: Sync status information
367
"""
368
```
369
370
### PIN Authentication
371
372
Handle PIN-based authentication for device registration.
373
374
```python { .api }
375
class MyPlexPinLogin:
376
"""PIN-based authentication for device registration."""
377
378
def __init__(self, oauth=False):
379
"""
380
Create PIN login flow.
381
382
Args:
383
oauth (bool): Use OAuth flow vs PIN flow
384
"""
385
386
@property
387
def pin(self):
388
"""str: Generated PIN for user entry."""
389
390
@property
391
def authenticated(self):
392
"""bool: Whether PIN has been authenticated."""
393
394
def checkLogin(self, timeout=60):
395
"""
396
Check if PIN has been authenticated.
397
398
Args:
399
timeout (int): Maximum time to wait for authentication
400
401
Returns:
402
MyPlexAccount: Authenticated account if successful
403
"""
404
```
405
406
## Usage Examples
407
408
### Basic Account Authentication
409
410
```python
411
from plexapi.myplex import MyPlexAccount
412
413
# Username/password authentication
414
account = MyPlexAccount('your-username', 'your-password')
415
416
# Token authentication
417
account = MyPlexAccount(token='your-auth-token')
418
419
# Two-factor authentication
420
account = MyPlexAccount('username', 'password', code='123456')
421
```
422
423
### Server Access
424
425
```python
426
# Get available servers
427
resources = account.resources()
428
for resource in resources:
429
print(f"Server: {resource.name} ({'owned' if resource.owned else 'shared'})")
430
431
# Connect to specific server
432
plex = account.resource('My Plex Server').connect()
433
434
# Alternative connection with options
435
plex = account.resource('My Plex Server').connect(ssl=True, timeout=30)
436
```
437
438
### User Management
439
440
```python
441
# Get current users
442
users = account.users()
443
for user in users:
444
user_type = "Home" if user.home else "Friend"
445
print(f"{user_type} User: {user.title} ({user.email})")
446
447
# Create managed home user
448
home_server = account.resource('Home Server').connect()
449
movie_section = home_server.library.section('Movies')
450
tv_section = home_server.library.section('TV Shows')
451
452
new_user = account.createHomeUser(
453
user='kid_username',
454
server=home_server,
455
sections=[movie_section, tv_section],
456
allowSync=True,
457
allowCameraUpload=False
458
)
459
460
# Invite friend
461
invitation = account.inviteFriend(
462
user='friend@example.com',
463
server=home_server,
464
sections=[movie_section],
465
allowSync=False
466
)
467
468
# Switch to managed user
469
kid_account = account.switchHomeUser('kid_username', pin='1234')
470
```
471
472
### Watchlist Management
473
474
```python
475
# Get watchlist
476
watchlist = account.watchlist()
477
print(f"Watchlist has {len(watchlist)} items")
478
479
# Filter watchlist
480
movies = account.watchlist(libtype='movie')
481
shows = account.watchlist(libtype='show')
482
483
# Add to watchlist (requires media objects from discovery or shared servers)
484
discovered = account.searchDiscover('spider-man', libtype='movie')
485
if discovered:
486
account.addToWatchlist(discovered[0])
487
488
# Check if item is on watchlist
489
movie = plex.library.section('Movies').get('The Matrix')
490
if account.onWatchlist(movie):
491
print("Movie is on watchlist")
492
```
493
494
### Content Discovery
495
496
```python
497
# Search for content to discover
498
results = account.searchDiscover('star wars', limit=10)
499
for item in results:
500
print(f"Discovered: {item.title} ({item.year})")
501
502
# Search by type
503
movies = account.searchDiscover('action', libtype='movie', limit=20)
504
shows = account.searchDiscover('comedy', libtype='show', limit=15)
505
```
506
507
### Device Management
508
509
```python
510
# Get registered devices
511
devices = account.devices()
512
for device in devices:
513
print(f"Device: {device.name} ({device.product})")
514
515
# Get specific device
516
phone = account.device(name='iPhone')
517
if phone:
518
print(f"Found device: {phone.clientIdentifier}")
519
```
520
521
### Playback History
522
523
```python
524
import datetime
525
526
# Get recent history
527
history = account.history(maxresults=50)
528
for entry in history:
529
print(f"Watched: {entry.title} on {entry.viewedAt}")
530
531
# Get history since specific date
532
week_ago = datetime.datetime.now() - datetime.timedelta(days=7)
533
recent = account.history(mindate=week_ago)
534
```
535
536
### Mobile Sync
537
538
```python
539
# Get sync items
540
sync_items = account.syncItems()
541
for item in sync_items:
542
print(f"Sync available: {item.title}")
543
544
# Get sync items for specific client
545
mobile_sync = account.syncItems(client='iPhone')
546
```
547
548
### PIN Authentication Flow
549
550
```python
551
from plexapi.myplex import MyPlexPinLogin
552
553
# Create PIN login
554
pin_login = MyPlexPinLogin()
555
print(f"Go to plex.tv/link and enter PIN: {pin_login.pin}")
556
557
# Wait for authentication
558
try:
559
account = pin_login.checkLogin(timeout=120) # Wait up to 2 minutes
560
print("Successfully authenticated!")
561
except Exception as e:
562
print(f"Authentication failed: {e}")
563
```
564
565
### Advanced User Permissions
566
567
```python
568
# Create user with detailed permissions
569
detailed_user = account.createHomeUser(
570
user='teenager',
571
server=home_server,
572
sections=[movie_section, tv_section, music_section],
573
allowSync=True,
574
allowCameraUpload=True,
575
allowChannelContent=False,
576
filterMovies='PG-13', # Content rating filter
577
filterTelevision='TV-14'
578
)
579
580
# Update sharing for existing friend
581
friend = account.user('friend@example.com')
582
# Note: Specific permission updates require server-level operations
583
```
584
585
### Error Handling
586
587
```python
588
from plexapi.exceptions import BadRequest, Unauthorized, TwoFactorRequired
589
590
try:
591
account = MyPlexAccount('username', 'password')
592
593
except TwoFactorRequired:
594
# Handle two-factor authentication
595
code = input("Enter 2FA code: ")
596
account = MyPlexAccount('username', 'password', code=code)
597
598
except Unauthorized:
599
print("Invalid credentials")
600
601
except BadRequest as e:
602
print(f"Request error: {e}")
603
```