0
# Users and Organizations
1

2
User lifecycle management, team operations, organization administration, and preference management with comprehensive search and filtering capabilities. This covers both individual user operations and multi-user/organization management functionality.
3

4
## Capabilities
5

6
### Current User Operations
7

8
Operations for managing the currently authenticated user's profile, preferences, organizations, and dashboard interactions.
9

10
```python { .api }
11
def get_actual_user(self):
12
    """
13
    Get current user information.
14
    
15
    Returns:
16
        dict: Current user profile including ID, login, name, email, roles
17
    """
18
    ...
19

20
def change_actual_user_password(self, old_password: str, new_password: str):
21
    """
22
    Change current user's password.
23
    
24
    Args:
25
        old_password (str): Current password
26
        new_password (str): New password
27
        
28
    Returns:
29
        dict: Password change result
30
    """
31
    ...
32

33
def switch_actual_user_organisation(self, organisation_id: int):
34
    """
35
    Switch current user's active organization.
36
    
37
    Args:
38
        organisation_id (int): Target organization ID
39
        
40
    Returns:
41
        dict: Switch result
42
    """
43
    ...
44

45
def get_actual_user_organisations(self):
46
    """
47
    Get current user's organization memberships.
48
    
49
    Returns:
50
        list: List of organizations user belongs to
51
    """
52
    ...
53

54
def get_actual_user_teams(self):
55
    """
56
    Get current user's team memberships.
57
    
58
    Returns:
59
        list: List of teams user belongs to
60
    """
61
    ...
62

63
def star_actual_user_dashboard(self, dashboard_id: int):
64
    """
65
    Star dashboard for current user.
66
    
67
    Args:
68
        dashboard_id (int): Dashboard ID to star
69
        
70
    Returns:
71
        dict: Star operation result
72
    """
73
    ...
74

75
def unstar_actual_user_dashboard(self, dashboard_id: int):
76
    """
77
    Unstar dashboard for current user.
78
    
79
    Args:
80
        dashboard_id (int): Dashboard ID to unstar
81
        
82
    Returns:
83
        dict: Unstar operation result
84
    """
85
    ...
86
```
87

88
**Current User Usage Example:**
89

90
```python
91
from grafana_client import GrafanaApi, TokenAuth
92

93
api = GrafanaApi(auth=TokenAuth("your-token"), host="grafana.example.com")
94

95
# Get current user info
96
user = api.user.get_actual_user()
97
print(f"Current user: {user['name']} ({user['email']})")
98
print(f"User ID: {user['id']}, Login: {user['login']}")
99

100
# Get user's organizations
101
orgs = api.user.get_actual_user_organisations()
102
for org in orgs:
103
    print(f"Organization: {org['name']} (ID: {org['orgId']}, Role: {org['role']})")
104

105
# Switch to different organization
106
if len(orgs) > 1:
107
    target_org = orgs[1]['orgId']
108
    api.user.switch_actual_user_organisation(target_org)
109
    print(f"Switched to organization {target_org}")
110

111
# Get user's teams
112
teams = api.user.get_actual_user_teams()
113
for team in teams:
114
    print(f"Team: {team['name']} (ID: {team['id']})")
115

116
# Star a dashboard
117
api.user.star_actual_user_dashboard(dashboard_id=123)
118
print("Dashboard starred successfully")
119
```
120

121
### Multi-User Operations
122

123
Operations for managing multiple users, searching users, and user administration across the organization.
124

125
```python { .api }
126
def search_users(self, query: Optional[str] = None, page: int = 1, perpage: int = 1000):
127
    """
128
    Search users in the organization.
129
    
130
    Args:
131
        query (Optional[str]): Search query (name, login, email)
132
        page (int): Page number (default: 1)
133
        perpage (int): Results per page (default: 1000, max: 5000)
134
        
135
    Returns:
136
        list: List of user objects matching search criteria
137
    """
138
    ...
139

140
def get_user(self, user_id: int):
141
    """
142
    Get user by ID.
143
    
144
    Args:
145
        user_id (int): User ID
146
        
147
    Returns:
148
        dict: User information including profile and organization memberships
149
    """
150
    ...
151

152
def find_user(self, login_or_email: str):
153
    """
154
    Find user by login or email address.
155
    
156
    Args:
157
        login_or_email (str): User login name or email address
158
        
159
    Returns:
160
        dict: User information if found
161
    """
162
    ...
163

164
def update_user(self, user_id: int, user: dict):
165
    """
166
    Update user information.
167
    
168
    Args:
169
        user_id (int): User ID
170
        user (dict): Updated user data (name, email, login, theme)
171
        
172
    Returns:
173
        dict: Update result
174
    """
175
    ...
176

177
def get_user_organisations(self, user_id: int):
178
    """
179
    Get user's organization memberships.
180
    
181
    Args:
182
        user_id (int): User ID
183
        
184
    Returns:
185
        list: List of organizations user belongs to
186
    """
187
    ...
188

189
def get_user_teams(self, user_id: int):
190
    """
191
    Get user's team memberships.
192
    
193
    Args:
194
        user_id (int): User ID
195
        
196
    Returns:
197
        list: List of teams user belongs to
198
    """
199
    ...
200
```
201

202
**Multi-User Usage Example:**
203

204
```python
205
# Search for users
206
all_users = api.users.search_users()
207
print(f"Total users in organization: {len(all_users)}")
208

209
# Search with query
210
admin_users = api.users.search_users(query="admin")
211
for user in admin_users:
212
    print(f"Admin user: {user['name']} ({user['login']})")
213

214
# Get specific user
215
user_details = api.users.get_user(user_id=2)
216
print(f"User details: {user_details}")
217

218
# Find user by email
219
user_by_email = api.users.find_user("admin@example.com")
220
if user_by_email:
221
    print(f"Found user: {user_by_email['name']}")
222

223
# Update user information
224
updated_user = {
225
    "name": "Updated Name",
226
    "email": "updated@example.com",
227
    "theme": "dark"
228
}
229
api.users.update_user(user_id=5, user=updated_user)
230
print("User updated successfully")
231

232
# Get user's organizations and teams
233
user_orgs = api.users.get_user_organisations(user_id=5)
234
user_teams = api.users.get_user_teams(user_id=5) 
235
print(f"User belongs to {len(user_orgs)} organizations and {len(user_teams)} teams")
236
```
237

238
### Team Operations
239

240
Comprehensive team management including creation, member management, and team preferences.
241

242
```python { .api }
243
def search_teams(self, query: Optional[str] = None, page: int = 1, perpage: int = 1000):
244
    """
245
    Search teams in the organization.
246
    
247
    Args:
248
        query (Optional[str]): Search query for team names
249
        page (int): Page number (default: 1)
250
        perpage (int): Results per page (default: 1000, max: 5000)
251
        
252
    Returns:
253
        list: List of team objects matching search criteria
254
    """
255
    ...
256

257
def get_team_by_name(self, team_name: str):
258
    """
259
    Get team by name.
260
    
261
    Args:
262
        team_name (str): Team name
263
        
264
    Returns:
265
        dict: Team information if found
266
    """
267
    ...
268

269
def get_team(self, team_id: int):
270
    """
271
    Get team by ID.
272
    
273
    Args:
274
        team_id (int): Team ID
275
        
276
    Returns:
277
        dict: Team information including member count
278
    """
279
    ...
280

281
def add_team(self, team: dict):
282
    """
283
    Create new team.
284
    
285
    Args:
286
        team (dict): Team data (name, email, optional orgId)
287
        
288
    Returns:
289
        dict: Created team with ID and metadata
290
    """
291
    ...
292

293
def update_team(self, team_id: int, team: dict):
294
    """
295
    Update team information.
296
    
297
    Args:
298
        team_id (int): Team ID
299
        team (dict): Updated team data (name, email)
300
        
301
    Returns:
302
        dict: Update result
303
    """
304
    ...
305

306
def delete_team(self, team_id: int):
307
    """
308
    Delete team.
309
    
310
    Args:
311
        team_id (int): Team ID
312
        
313
    Returns:
314
        dict: Deletion result
315
    """
316
    ...
317

318
def get_team_members(self, team_id: int):
319
    """
320
    Get team members.
321
    
322
    Args:
323
        team_id (int): Team ID
324
        
325
    Returns:
326
        list: List of team members with user info and roles
327
    """
328
    ...
329

330
def add_team_member(self, team_id: int, user_id: int):
331
    """
332
    Add user to team.
333
    
334
    Args:
335
        team_id (int): Team ID
336
        user_id (int): User ID to add
337
        
338
    Returns:
339
        dict: Add member result
340
    """
341
    ...
342

343
def remove_team_member(self, team_id: int, user_id: int):
344
    """
345
    Remove user from team.
346
    
347
    Args:
348
        team_id (int): Team ID
349
        user_id (int): User ID to remove
350
        
351
    Returns:
352
        dict: Remove member result
353
    """
354
    ...
355
```
356

357
**Team Operations Usage Example:**
358

359
```python
360
# Search for teams
361
all_teams = api.teams.search_teams()
362
print(f"Total teams: {len(all_teams)}")
363

364
dev_teams = api.teams.search_teams(query="dev")
365
for team in dev_teams:
366
    print(f"Dev team: {team['name']} (ID: {team['id']})")
367

368
# Create new team
369
new_team = {
370
    "name": "Platform Engineering", 
371
    "email": "platform@example.com"
372
}
373
created_team = api.teams.add_team(new_team)
374
team_id = created_team['teamId']
375
print(f"Created team with ID: {team_id}")
376

377
# Get team details
378
team_details = api.teams.get_team(team_id)
379
print(f"Team: {team_details['name']} ({team_details['memberCount']} members)")
380

381
# Add members to team
382
user_ids = [2, 3, 5]  # User IDs to add
383
for user_id in user_ids:
384
    try:
385
        api.teams.add_team_member(team_id, user_id)
386
        print(f"Added user {user_id} to team")
387
    except Exception as e:
388
        print(f"Failed to add user {user_id}: {e}")
389

390
# Get team members
391
members = api.teams.get_team_members(team_id)
392
for member in members:
393
    print(f"Member: {member['name']} ({member['login']}) - {member['permission']}")
394

395
# Update team
396
api.teams.update_team(team_id, {
397
    "name": "Platform Engineering Team",
398
    "email": "platform-team@example.com"
399
})
400
```
401

402
### Organization Operations
403

404
Managing current organization settings, users, and preferences.
405

406
```python { .api }
407
def find_organization(self, org_name: str):
408
    """
409
    Find organization by name.
410
    
411
    Args:
412
        org_name (str): Organization name
413
        
414
    Returns:
415
        dict: Organization information if found
416
    """
417
    ...
418

419
def get_current_organization(self):
420
    """
421
    Get current organization information.
422
    
423
    Returns:
424
        dict: Current organization details
425
    """
426
    ...
427

428
def create_organization(self, organization: dict):
429
    """
430
    Create new organization.
431
    
432
    Args:
433
        organization (dict): Organization data (name)
434
        
435
    Returns:
436
        dict: Created organization with ID
437
    """
438
    ...
439

440
def update_current_organization(self, organization: dict):
441
    """
442
    Update current organization.
443
    
444
    Args:
445
        organization (dict): Updated organization data (name)
446
        
447
    Returns:
448
        dict: Update result
449
    """
450
    ...
451

452
def get_current_organization_users(self):
453
    """
454
    Get users in current organization.
455
    
456
    Returns:
457
        list: List of users in current organization
458
    """
459
    ...
460

461
def add_user_current_organization(self, user: dict):
462
    """
463
    Add user to current organization.
464
    
465
    Args:
466
        user (dict): User data (loginOrEmail, role)
467
        
468
    Returns:
469
        dict: Add user result
470
    """
471
    ...
472

473
def update_user_current_organization(self, user_id: int, user: dict):
474
    """
475
    Update user role in current organization.
476
    
477
    Args:
478
        user_id (int): User ID
479
        user (dict): Updated user data (role)
480
        
481
    Returns:
482
        dict: Update result
483
    """
484
    ...
485

486
def delete_user_current_organization(self, user_id: int):
487
    """
488
    Remove user from current organization.
489
    
490
    Args:
491
        user_id (int): User ID to remove
492
        
493
    Returns:
494
        dict: Removal result
495
    """
496
    ...
497
```
498

499
### Multi-Organization Operations
500

501
Managing multiple organizations and cross-organization user assignments.
502

503
```python { .api }
504
def list_organization(self):
505
    """
506
    List all organizations (admin only).
507
    
508
    Returns:
509
        list: List of all organizations
510
    """
511
    ...
512

513
def update_organization(self, organization_id: int, organization: dict):
514
    """
515
    Update organization by ID (admin only).
516
    
517
    Args:
518
        organization_id (int): Organization ID
519
        organization (dict): Updated organization data
520
        
521
    Returns:
522
        dict: Update result
523
    """
524
    ...
525

526
def delete_organization(self, organization_id: int):
527
    """
528
    Delete organization (admin only).
529
    
530
    Args:
531
        organization_id (int): Organization ID to delete
532
        
533
    Returns:
534
        dict: Deletion result
535
    """
536
    ...
537

538
def switch_organization(self, organization_id: int):
539
    """
540
    Switch to different organization context.
541
    
542
    Args:
543
        organization_id (int): Target organization ID
544
        
545
    Returns:
546
        dict: Switch result
547
    """
548
    ...
549

550
def organization_user_list(self, organization_id: int):
551
    """
552
    List users in specific organization.
553
    
554
    Args:
555
        organization_id (int): Organization ID
556
        
557
    Returns:
558
        list: List of users in organization
559
    """
560
    ...
561

562
def organization_user_add(self, organization_id: int, user: dict):
563
    """
564
    Add user to specific organization.
565
    
566
    Args:
567
        organization_id (int): Organization ID
568
        user (dict): User data (loginOrEmail, role)
569
        
570
    Returns:
571
        dict: Add user result
572
    """
573
    ...
574

575
def organization_user_update(self, organization_id: int, user_id: int, user_role: str):
576
    """
577
    Update user role in specific organization.
578
    
579
    Args:
580
        organization_id (int): Organization ID
581
        user_id (int): User ID
582
        user_role (str): New role (Viewer, Editor, Admin)
583
        
584
    Returns:
585
        dict: Update result
586
    """
587
    ...
588

589
def organization_user_delete(self, organization_id: int, user_id: int):
590
    """
591
    Remove user from specific organization.
592
    
593
    Args:
594
        organization_id (int): Organization ID
595
        user_id (int): User ID to remove
596
        
597
    Returns:
598
        dict: Removal result
599
    """
600
    ...
601
```
602

603
**Organization Management Usage Example:**
604

605
```python
606
# Get current organization
607
current_org = api.organization.get_current_organization()
608
print(f"Current org: {current_org['name']} (ID: {current_org['id']})")
609

610
# List all organizations (admin only)
611
try:
612
    all_orgs = api.organizations.list_organization()
613
    print(f"Total organizations: {len(all_orgs)}")
614
    for org in all_orgs:
615
        print(f"Org: {org['name']} (ID: {org['id']})")
616
except Exception as e:
617
    print(f"Access denied or error: {e}")
618

619
# Get users in current organization
620
org_users = api.organization.get_current_organization_users()
621
print(f"Users in current org: {len(org_users)}")
622

623
# Add user to organization
624
new_org_user = {
625
    "loginOrEmail": "newuser@example.com",
626
    "role": "Editor"
627
}
628
try:
629
    api.organization.add_user_current_organization(new_org_user)
630
    print("User added to organization")
631
except Exception as e:
632
    print(f"Failed to add user: {e}")
633

634
# Update user role
635
api.organization.update_user_current_organization(
636
    user_id=10, 
637
    user={"role": "Admin"}
638
)
639
print("User role updated")
640
```
641

642
### User Preferences
643

644
Managing user, team, and organization preferences including themes, locales, and dashboard settings.
645

646
```python { .api }
647
# User preferences (through User API)
648
def get_preferences(self):
649
    """
650
    Get current user preferences.
651
    
652
    Returns:
653
        PersonalPreferences: User preferences object
654
    """
655
    ...
656

657
def update_preferences(self, preferences):
658
    """
659
    Update current user preferences (full update).
660
    
661
    Args:
662
        preferences (PersonalPreferences): Complete preferences object
663
        
664
    Returns:
665
        dict: Update result
666
    """
667
    ...
668

669
def patch_preferences(self, preferences):
670
    """
671
    Update current user preferences (partial update).
672
    
673
    Args:
674
        preferences (PersonalPreferences): Partial preferences object
675
        
676
    Returns:
677
        dict: Update result
678
    """
679
    ...
680

681
# Team preferences (through Teams API)  
682
def update_preferences(self, team_id: int, preferences):
683
    """
684
    Update team preferences.
685
    
686
    Args:
687
        team_id (int): Team ID
688
        preferences (PersonalPreferences): Team preferences
689
        
690
    Returns:
691
        dict: Update result
692
    """
693
    ...
694

695
# Organization preferences (through Organization API)
696
def get_preferences(self):
697
    """Get organization preferences"""
698
    ...
699

700
def update_preferences(self, preferences):
701
    """Update organization preferences (full)"""
702
    ...
703

704
def patch_preferences(self, preferences):
705
    """Update organization preferences (partial)"""
706
    ...
707
```
708

709
**Preferences Usage Example:**
710

711
```python
712
from grafana_client.model import PersonalPreferences
713

714
# Get current user preferences
715
user_prefs = api.user.get_preferences()
716
print(f"User theme: {user_prefs.theme}")
717
print(f"User timezone: {user_prefs.timezone}")
718

719
# Update user preferences
720
new_prefs = PersonalPreferences(
721
    theme="dark",
722
    timezone="America/New_York",
723
    homeDashboardUID="home-dashboard-uid",
724
    locale="en-US"
725
)
726

727
api.user.update_preferences(new_prefs)
728
print("User preferences updated")
729

730
# Partial preference update
731
partial_prefs = PersonalPreferences(theme="light")
732
api.user.patch_preferences(partial_prefs)
733
print("User theme updated to light")
734

735
# Update team preferences
736
team_prefs = PersonalPreferences(
737
    theme="dark",
738
    timezone="UTC"
739
)
740
api.teams.update_preferences(team_id=5, preferences=team_prefs)
741

742
# Get and update organization preferences
743
org_prefs = api.organization.get_preferences()
744
org_prefs.theme = "light"
745
api.organization.update_preferences(org_prefs)
746
```
747

748
### Async User and Organization Operations
749

750
All user and organization operations support async versions:
751

752
```python
753
import asyncio
754
from grafana_client import AsyncGrafanaApi, TokenAuth
755

756
async def manage_users_and_orgs():
757
    api = AsyncGrafanaApi(auth=TokenAuth("your-token"), host="grafana.example.com")
758
    
759
    # Concurrent user operations
760
    user_tasks = [
761
        api.user.get_actual_user(),
762
        api.user.get_actual_user_organisations(), 
763
        api.user.get_actual_user_teams()
764
    ]
765
    
766
    current_user, user_orgs, user_teams = await asyncio.gather(*user_tasks)
767
    
768
    print(f"User: {current_user['name']}")
769
    print(f"Organizations: {len(user_orgs)}")
770
    print(f"Teams: {len(user_teams)}")
771
    
772
    # Concurrent team operations
773
    teams = await api.teams.search_teams()
774
    team_detail_tasks = [
775
        api.teams.get_team(team['id'])
776
        for team in teams[:5]  # First 5 teams
777
    ]
778
    
779
    team_details = await asyncio.gather(*team_detail_tasks)
780
    for team in team_details:
781
        print(f"Team: {team['name']} ({team['memberCount']} members)")
782

783
asyncio.run(manage_users_and_orgs())
784
```
785

786
### Best Practices
787

788
1. **Role Management**: Use appropriate roles (Viewer, Editor, Admin) based on user responsibilities
789
2. **Team Organization**: Organize users into logical teams for easier permission management
790
3. **Preference Management**: Set reasonable defaults at organization level, allow user customization
791
4. **Search Optimization**: Use pagination and filtering for large user/team datasets
792
5. **Organization Context**: Be aware of current organization context when performing operations
793
6. **Error Handling**: Handle permission errors gracefully, especially for admin operations
794
7. **Async for Scale**: Use async API for bulk user/team operations
795
8. **Audit Trail**: Track user and organization changes for security and compliance