Overview
The ActiveUserResource provides methods for managing the currently authenticated user’s profile, projects, and settings. Access it via client.active_user after authenticating your SpeckleClient.
This resource represents your own user account and provides access to personal information, projects you have access to, and workspace memberships.
from specklepy.api.client import SpeckleClient
client = SpeckleClient(host="https://app.speckle.systems")
client.authenticate_with_token(token)
# Access active user operations
user = client.active_user.get()
print(f"Logged in as: {user.name}")
Methods
get()
Get your own user profile information.
client.active_user.get() -> Optional[User]
Your user profile, or None if not authenticated. See User user = client.active_user.get()
if user:
print(f"Name: {user.name}")
print(f"Email: {user.email}")
print(f"Bio: {user.bio}")
print(f"Company: {user.company}")
print(f"Avatar: {user.avatar}")
print(f"Verified: {user.verified}")
print(f"Role: {user.role}")
else:
print("Not authenticated")
update()
Update your user profile.
client.active_user.update(input: UserUpdateInput) -> User
The updated user profile. See User from specklepy.core.api.inputs.user_inputs import UserUpdateInput
updated_user = client.active_user.update(UserUpdateInput(
name="Jane Smith",
bio="Structural Engineer specializing in BIM workflows",
company="ACME Engineering"
))
print(f"Updated profile: {updated_user.name}")
name (str, optional) - New display namebio (str, optional) - New biographycompany (str, optional) - New company nameavatar (str, optional) - New avatar URL
Email and other sensitive fields cannot be updated via the API. Use the web interface to change your email address.
get_projects()
Get all projects you have access to.
When to use this method:
- Non-workspace servers (self-hosted/open-source): Use this method to list all projects you have access to.
- Workspace-enabled servers (e.g., app.speckle.systems): Use this method with filters to list personal projects, or use
client.workspace.get_projects(workspace_id) to list projects within a specific workspace.
For workspace-enabled servers, consider using UserProjectsFilter(personalOnly=True) to explicitly get only your personal projects, or filter by workspaceId for workspace projects.Note: In earlier versions of specklepy, this functionality was provided by the stream resource with a list() method. client.active_user.get_projects(
*,
limit: int = 25,
cursor: Optional[str] = None,
filter: Optional[UserProjectsFilter] = None
) -> ResourceCollection[Project]
Maximum number of projects to return
filter
UserProjectsFilter
default:"None"
projects
ResourceCollection[Project]
Collection of projects
# Get all your projects
projects = client.active_user.get_projects(limit=50)
print(f"You have access to {projects.totalCount} projects:")
for project in projects.items:
print(f" - {project.name} ({project.role})")
# Paginate through more projects
if projects.cursor:
next_page = client.active_user.get_projects(cursor=projects.cursor)
See [UserProjectsFilter](#userprojectsfilter) for filtering options.
get_projects_with_permissions()
Get your projects with detailed permission information.
client.active_user.get_projects_with_permissions(
*,
limit: int = 25,
cursor: Optional[str] = None,
filter: Optional[UserProjectsFilter] = None
) -> ResourceCollection[ProjectWithPermissions]
Maximum number of projects to return
filter
UserProjectsFilter
default:"None"
projects
ResourceCollection[ProjectWithPermissions]
Projects with permissions
projects = client.active_user.get_projects_with_permissions(limit=10)
for project in projects.items:
print(f"\n{project.name}:")
if project.permissions.canCreateModel.authorized:
print(" ✓ Can create models")
if project.permissions.canDelete.authorized:
print(" ✓ Can delete project")
if project.permissions.canPublish.authorized:
print(" ✓ Can publish versions")
if not project.permissions.canLoad.authorized:
print(f" ✗ Cannot load: {project.permissions.canLoad.message}")
This method is useful when you need to check permissions before attempting operations, helping you build more robust applications.
get_project_invites()
Get pending project invitations.
client.active_user.get_project_invites() -> List[PendingStreamCollaborator]
invites
List[PendingStreamCollaborator]
List of pending invitations
invites = client.active_user.get_project_invites()
if invites:
print(f"You have {len(invites)} pending invitations:")
for invite in invites:
print(f"\n Project: {invite.projectName}")
print(f" Role: {invite.role}")
print(f" Invited by: {invite.invitedBy.name}")
print(f" Invite ID: {invite.inviteId}")
else:
print("No pending invitations")
Use the Speckle web interface to accept or decline invitations. This method only retrieves pending invitations. See PendingStreamCollaborator for property details. can_create_personal_projects()
Check if you have permission to create personal (non-workspace) projects.
client.active_user.can_create_personal_projects() -> PermissionCheckResult
permission = client.active_user.can_create_personal_projects()
if permission.authorized:
print("✓ You can create personal projects")
# Safe to create project
from specklepy.core.api.inputs.project_inputs import ProjectCreateInput
project = client.project.create(ProjectCreateInput(
name="My Personal Project"
))
else:
print(f"✗ Cannot create personal projects: {permission.message}")
print(f" Code: {permission.code}")
get_workspaces()
Get workspaces you’re a member of (workspace-enabled servers only).
client.active_user.get_workspaces(
limit: int = 25,
cursor: Optional[str] = None,
filter: Optional[UserWorkspacesFilter] = None
) -> ResourceCollection[Workspace]
Maximum number of workspaces to return
filter
UserWorkspacesFilter
default:"None"
workspaces
ResourceCollection[Workspace]
Collection of workspaces
workspaces = client.active_user.get_workspaces()
print(f"You're a member of {workspaces.totalCount} workspaces:")
for workspace in workspaces.items:
print(f"\n {workspace.name}")
print(f" Role: {workspace.role}")
print(f" Slug: {workspace.slug}")
if workspace.permissions.canCreateProject.authorized:
print(f" ✓ Can create projects")
This method only works on workspace-enabled servers (e.g., app.speckle.systems). On other servers, it will raise an error.
get_active_workspace()
Get your currently active workspace (workspace-enabled servers only).
client.active_user.get_active_workspace() -> Optional[LimitedWorkspace]
Active workspace, or None if none selected
active_workspace = client.active_user.get_active_workspace()
if active_workspace:
print(f"Active workspace: {active_workspace.name}")
print(f"Role: {active_workspace.role}")
print(f"Description: {active_workspace.description}")
else:
print("No active workspace")
This method only works on workspace-enabled servers (e.g., app.speckle.systems).
Types
User
Represents a Speckle user’s full profile (your own account).
Whether email is verified
Server role (e.g., “server:user”, “server:admin”)
PendingStreamCollaborator
Represents a pending project invitation.
UserUpdateInput(
avatar: Optional[str] = None,
bio: Optional[str] = None,
company: Optional[str] = None,
name: Optional[str] = None
)
update().
Fields:
avatar (str, optional) - Avatar image URLbio (str, optional) - User biographycompany (str, optional) - Company namename (str, optional) - Display name
Filters
UserProjectsFilter
UserProjectsFilter(
search: Optional[str] = None,
only_with_roles: Optional[Sequence[str]] = None,
workspace_id: Optional[str] = None,
personal_only: Optional[bool] = None,
include_implicit_access: Optional[bool] = None
)
get_projects() and get_projects_with_permissions().
Fields:
search (str, optional) - Search by project name or descriptiononly_with_roles (List[str], optional) - Filter by user rolesworkspace_id (str, optional) - Filter to specific workspacepersonal_only (bool, optional) - Only return personal (non-workspace) projectsinclude_implicit_access (bool, optional) - Include projects with implicit access
UserWorkspacesFilter
UserWorkspacesFilter(
search: Optional[str] = None
)
get_workspaces().
Fields:
search (str, optional) - Search by workspace name
