tessl/pypi-grafana-client
A client library for accessing the Grafana HTTP API, written in Python
—
Pending
users-and-orgs.mddocs/
Users and Organizations
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.
Capabilities
Current User Operations
Operations for managing the currently authenticated user's profile, preferences, organizations, and dashboard interactions.
def get_actual_user(self):
"""
Get current user information.
Returns:
dict: Current user profile including ID, login, name, email, roles
"""
...
def change_actual_user_password(self, old_password: str, new_password: str):
"""
Change current user's password.
Args:
old_password (str): Current password
new_password (str): New password
Returns:
dict: Password change result
"""
...
def switch_actual_user_organisation(self, organisation_id: int):
"""
Switch current user's active organization.
Args:
organisation_id (int): Target organization ID
Returns:
dict: Switch result
"""
...
def get_actual_user_organisations(self):
"""
Get current user's organization memberships.
Returns:
list: List of organizations user belongs to
"""
...
def get_actual_user_teams(self):
"""
Get current user's team memberships.
Returns:
list: List of teams user belongs to
"""
...
def star_actual_user_dashboard(self, dashboard_id: int):
"""
Star dashboard for current user.
Args:
dashboard_id (int): Dashboard ID to star
Returns:
dict: Star operation result
"""
...
def unstar_actual_user_dashboard(self, dashboard_id: int):
"""
Unstar dashboard for current user.
Args:
dashboard_id (int): Dashboard ID to unstar
Returns:
dict: Unstar operation result
"""
...Current User Usage Example:
from grafana_client import GrafanaApi, TokenAuth
api = GrafanaApi(auth=TokenAuth("your-token"), host="grafana.example.com")
# Get current user info
user = api.user.get_actual_user()
print(f"Current user: {user['name']} ({user['email']})")
print(f"User ID: {user['id']}, Login: {user['login']}")
# Get user's organizations
orgs = api.user.get_actual_user_organisations()
for org in orgs:
print(f"Organization: {org['name']} (ID: {org['orgId']}, Role: {org['role']})")
# Switch to different organization
if len(orgs) > 1:
target_org = orgs[1]['orgId']
api.user.switch_actual_user_organisation(target_org)
print(f"Switched to organization {target_org}")
# Get user's teams
teams = api.user.get_actual_user_teams()
for team in teams:
print(f"Team: {team['name']} (ID: {team['id']})")
# Star a dashboard
api.user.star_actual_user_dashboard(dashboard_id=123)
print("Dashboard starred successfully")Multi-User Operations
Operations for managing multiple users, searching users, and user administration across the organization.
def search_users(self, query: Optional[str] = None, page: int = 1, perpage: int = 1000):
"""
Search users in the organization.
Args:
query (Optional[str]): Search query (name, login, email)
page (int): Page number (default: 1)
perpage (int): Results per page (default: 1000, max: 5000)
Returns:
list: List of user objects matching search criteria
"""
...
def get_user(self, user_id: int):
"""
Get user by ID.
Args:
user_id (int): User ID
Returns:
dict: User information including profile and organization memberships
"""
...
def find_user(self, login_or_email: str):
"""
Find user by login or email address.
Args:
login_or_email (str): User login name or email address
Returns:
dict: User information if found
"""
...
def update_user(self, user_id: int, user: dict):
"""
Update user information.
Args:
user_id (int): User ID
user (dict): Updated user data (name, email, login, theme)
Returns:
dict: Update result
"""
...
def get_user_organisations(self, user_id: int):
"""
Get user's organization memberships.
Args:
user_id (int): User ID
Returns:
list: List of organizations user belongs to
"""
...
def get_user_teams(self, user_id: int):
"""
Get user's team memberships.
Args:
user_id (int): User ID
Returns:
list: List of teams user belongs to
"""
...Multi-User Usage Example:
# Search for users
all_users = api.users.search_users()
print(f"Total users in organization: {len(all_users)}")
# Search with query
admin_users = api.users.search_users(query="admin")
for user in admin_users:
print(f"Admin user: {user['name']} ({user['login']})")
# Get specific user
user_details = api.users.get_user(user_id=2)
print(f"User details: {user_details}")
# Find user by email
user_by_email = api.users.find_user("admin@example.com")
if user_by_email:
print(f"Found user: {user_by_email['name']}")
# Update user information
updated_user = {
"name": "Updated Name",
"email": "updated@example.com",
"theme": "dark"
}
api.users.update_user(user_id=5, user=updated_user)
print("User updated successfully")
# Get user's organizations and teams
user_orgs = api.users.get_user_organisations(user_id=5)
user_teams = api.users.get_user_teams(user_id=5)
print(f"User belongs to {len(user_orgs)} organizations and {len(user_teams)} teams")Team Operations
Comprehensive team management including creation, member management, and team preferences.
def search_teams(self, query: Optional[str] = None, page: int = 1, perpage: int = 1000):
"""
Search teams in the organization.
Args:
query (Optional[str]): Search query for team names
page (int): Page number (default: 1)
perpage (int): Results per page (default: 1000, max: 5000)
Returns:
list: List of team objects matching search criteria
"""
...
def get_team_by_name(self, team_name: str):
"""
Get team by name.
Args:
team_name (str): Team name
Returns:
dict: Team information if found
"""
...
def get_team(self, team_id: int):
"""
Get team by ID.
Args:
team_id (int): Team ID
Returns:
dict: Team information including member count
"""
...
def add_team(self, team: dict):
"""
Create new team.
Args:
team (dict): Team data (name, email, optional orgId)
Returns:
dict: Created team with ID and metadata
"""
...
def update_team(self, team_id: int, team: dict):
"""
Update team information.
Args:
team_id (int): Team ID
team (dict): Updated team data (name, email)
Returns:
dict: Update result
"""
...
def delete_team(self, team_id: int):
"""
Delete team.
Args:
team_id (int): Team ID
Returns:
dict: Deletion result
"""
...
def get_team_members(self, team_id: int):
"""
Get team members.
Args:
team_id (int): Team ID
Returns:
list: List of team members with user info and roles
"""
...
def add_team_member(self, team_id: int, user_id: int):
"""
Add user to team.
Args:
team_id (int): Team ID
user_id (int): User ID to add
Returns:
dict: Add member result
"""
...
def remove_team_member(self, team_id: int, user_id: int):
"""
Remove user from team.
Args:
team_id (int): Team ID
user_id (int): User ID to remove
Returns:
dict: Remove member result
"""
...Team Operations Usage Example:
# Search for teams
all_teams = api.teams.search_teams()
print(f"Total teams: {len(all_teams)}")
dev_teams = api.teams.search_teams(query="dev")
for team in dev_teams:
print(f"Dev team: {team['name']} (ID: {team['id']})")
# Create new team
new_team = {
"name": "Platform Engineering",
"email": "platform@example.com"
}
created_team = api.teams.add_team(new_team)
team_id = created_team['teamId']
print(f"Created team with ID: {team_id}")
# Get team details
team_details = api.teams.get_team(team_id)
print(f"Team: {team_details['name']} ({team_details['memberCount']} members)")
# Add members to team
user_ids = [2, 3, 5] # User IDs to add
for user_id in user_ids:
try:
api.teams.add_team_member(team_id, user_id)
print(f"Added user {user_id} to team")
except Exception as e:
print(f"Failed to add user {user_id}: {e}")
# Get team members
members = api.teams.get_team_members(team_id)
for member in members:
print(f"Member: {member['name']} ({member['login']}) - {member['permission']}")
# Update team
api.teams.update_team(team_id, {
"name": "Platform Engineering Team",
"email": "platform-team@example.com"
})Organization Operations
Managing current organization settings, users, and preferences.
def find_organization(self, org_name: str):
"""
Find organization by name.
Args:
org_name (str): Organization name
Returns:
dict: Organization information if found
"""
...
def get_current_organization(self):
"""
Get current organization information.
Returns:
dict: Current organization details
"""
...
def create_organization(self, organization: dict):
"""
Create new organization.
Args:
organization (dict): Organization data (name)
Returns:
dict: Created organization with ID
"""
...
def update_current_organization(self, organization: dict):
"""
Update current organization.
Args:
organization (dict): Updated organization data (name)
Returns:
dict: Update result
"""
...
def get_current_organization_users(self):
"""
Get users in current organization.
Returns:
list: List of users in current organization
"""
...
def add_user_current_organization(self, user: dict):
"""
Add user to current organization.
Args:
user (dict): User data (loginOrEmail, role)
Returns:
dict: Add user result
"""
...
def update_user_current_organization(self, user_id: int, user: dict):
"""
Update user role in current organization.
Args:
user_id (int): User ID
user (dict): Updated user data (role)
Returns:
dict: Update result
"""
...
def delete_user_current_organization(self, user_id: int):
"""
Remove user from current organization.
Args:
user_id (int): User ID to remove
Returns:
dict: Removal result
"""
...Multi-Organization Operations
Managing multiple organizations and cross-organization user assignments.
def list_organization(self):
"""
List all organizations (admin only).
Returns:
list: List of all organizations
"""
...
def update_organization(self, organization_id: int, organization: dict):
"""
Update organization by ID (admin only).
Args:
organization_id (int): Organization ID
organization (dict): Updated organization data
Returns:
dict: Update result
"""
...
def delete_organization(self, organization_id: int):
"""
Delete organization (admin only).
Args:
organization_id (int): Organization ID to delete
Returns:
dict: Deletion result
"""
...
def switch_organization(self, organization_id: int):
"""
Switch to different organization context.
Args:
organization_id (int): Target organization ID
Returns:
dict: Switch result
"""
...
def organization_user_list(self, organization_id: int):
"""
List users in specific organization.
Args:
organization_id (int): Organization ID
Returns:
list: List of users in organization
"""
...
def organization_user_add(self, organization_id: int, user: dict):
"""
Add user to specific organization.
Args:
organization_id (int): Organization ID
user (dict): User data (loginOrEmail, role)
Returns:
dict: Add user result
"""
...
def organization_user_update(self, organization_id: int, user_id: int, user_role: str):
"""
Update user role in specific organization.
Args:
organization_id (int): Organization ID
user_id (int): User ID
user_role (str): New role (Viewer, Editor, Admin)
Returns:
dict: Update result
"""
...
def organization_user_delete(self, organization_id: int, user_id: int):
"""
Remove user from specific organization.
Args:
organization_id (int): Organization ID
user_id (int): User ID to remove
Returns:
dict: Removal result
"""
...Organization Management Usage Example:
# Get current organization
current_org = api.organization.get_current_organization()
print(f"Current org: {current_org['name']} (ID: {current_org['id']})")
# List all organizations (admin only)
try:
all_orgs = api.organizations.list_organization()
print(f"Total organizations: {len(all_orgs)}")
for org in all_orgs:
print(f"Org: {org['name']} (ID: {org['id']})")
except Exception as e:
print(f"Access denied or error: {e}")
# Get users in current organization
org_users = api.organization.get_current_organization_users()
print(f"Users in current org: {len(org_users)}")
# Add user to organization
new_org_user = {
"loginOrEmail": "newuser@example.com",
"role": "Editor"
}
try:
api.organization.add_user_current_organization(new_org_user)
print("User added to organization")
except Exception as e:
print(f"Failed to add user: {e}")
# Update user role
api.organization.update_user_current_organization(
user_id=10,
user={"role": "Admin"}
)
print("User role updated")User Preferences
Managing user, team, and organization preferences including themes, locales, and dashboard settings.
# User preferences (through User API)
def get_preferences(self):
"""
Get current user preferences.
Returns:
PersonalPreferences: User preferences object
"""
...
def update_preferences(self, preferences):
"""
Update current user preferences (full update).
Args:
preferences (PersonalPreferences): Complete preferences object
Returns:
dict: Update result
"""
...
def patch_preferences(self, preferences):
"""
Update current user preferences (partial update).
Args:
preferences (PersonalPreferences): Partial preferences object
Returns:
dict: Update result
"""
...
# Team preferences (through Teams API)
def update_preferences(self, team_id: int, preferences):
"""
Update team preferences.
Args:
team_id (int): Team ID
preferences (PersonalPreferences): Team preferences
Returns:
dict: Update result
"""
...
# Organization preferences (through Organization API)
def get_preferences(self):
"""Get organization preferences"""
...
def update_preferences(self, preferences):
"""Update organization preferences (full)"""
...
def patch_preferences(self, preferences):
"""Update organization preferences (partial)"""
...Preferences Usage Example:
from grafana_client.model import PersonalPreferences
# Get current user preferences
user_prefs = api.user.get_preferences()
print(f"User theme: {user_prefs.theme}")
print(f"User timezone: {user_prefs.timezone}")
# Update user preferences
new_prefs = PersonalPreferences(
theme="dark",
timezone="America/New_York",
homeDashboardUID="home-dashboard-uid",
locale="en-US"
)
api.user.update_preferences(new_prefs)
print("User preferences updated")
# Partial preference update
partial_prefs = PersonalPreferences(theme="light")
api.user.patch_preferences(partial_prefs)
print("User theme updated to light")
# Update team preferences
team_prefs = PersonalPreferences(
theme="dark",
timezone="UTC"
)
api.teams.update_preferences(team_id=5, preferences=team_prefs)
# Get and update organization preferences
org_prefs = api.organization.get_preferences()
org_prefs.theme = "light"
api.organization.update_preferences(org_prefs)Async User and Organization Operations
All user and organization operations support async versions:
import asyncio
from grafana_client import AsyncGrafanaApi, TokenAuth
async def manage_users_and_orgs():
api = AsyncGrafanaApi(auth=TokenAuth("your-token"), host="grafana.example.com")
# Concurrent user operations
user_tasks = [
api.user.get_actual_user(),
api.user.get_actual_user_organisations(),
api.user.get_actual_user_teams()
]
current_user, user_orgs, user_teams = await asyncio.gather(*user_tasks)
print(f"User: {current_user['name']}")
print(f"Organizations: {len(user_orgs)}")
print(f"Teams: {len(user_teams)}")
# Concurrent team operations
teams = await api.teams.search_teams()
team_detail_tasks = [
api.teams.get_team(team['id'])
for team in teams[:5] # First 5 teams
]
team_details = await asyncio.gather(*team_detail_tasks)
for team in team_details:
print(f"Team: {team['name']} ({team['memberCount']} members)")
asyncio.run(manage_users_and_orgs())Best Practices
- Role Management: Use appropriate roles (Viewer, Editor, Admin) based on user responsibilities
- Team Organization: Organize users into logical teams for easier permission management
- Preference Management: Set reasonable defaults at organization level, allow user customization
- Search Optimization: Use pagination and filtering for large user/team datasets
- Organization Context: Be aware of current organization context when performing operations
- Error Handling: Handle permission errors gracefully, especially for admin operations
- Async for Scale: Use async API for bulk user/team operations
- Audit Trail: Track user and organization changes for security and compliance
Install with Tessl CLI
npx tessl i tessl/pypi-grafana-client@5.0.1