ActiveUserResource

Complete API reference for active user operations in SpecklePy

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]

Parameters: None

Returns:

user · User | None

Your user profile, or None if not authenticated. See User

Example:

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

Parameters:

input · UserUpdateInput · required

Profile update parameters. See UserUpdateInput

Returns:

user · User

The updated user profile. See User

Example:

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}")

UserUpdateInput Fields:

• name (str, optional) - New display name
• bio (str, optional) - New biography
• company (str, optional) - New company name
• avatar (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]

Parameters:

limit · int · default: "25"

Maximum number of projects to return

cursor · str · default: "None"

Cursor for pagination

filter · UserProjectsFilter · default: "None"

Filter criteria. See UserProjectsFilter

Returns:

projects · ResourceCollection[Project]

Collection of projects

Example:

# 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)

With Filtering:

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]

Parameters:

limit · int · default: "25"

Maximum number of projects to return

cursor · str · default: "None"

Cursor for pagination

filter · UserProjectsFilter · default: "None"

Filter criteria. See UserProjectsFilter

Returns:

projects · ResourceCollection[ProjectWithPermissions]

Projects with permissions

Example:

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]

Parameters: None

Returns:

invites · List[PendingStreamCollaborator]

List of pending invitations

Example:

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

Parameters: None

Returns:

permission · PermissionCheckResult

Permission check result. See PermissionCheckResult

Example:

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]

Parameters:

limit · int · default: "25"

Maximum number of workspaces to return

cursor · str · default: "None"

Cursor for pagination

filter · UserWorkspacesFilter · default: "None"

Filter criteria. See UserWorkspacesFilter

Returns:

workspaces · ResourceCollection[Workspace]

Collection of workspaces

Example:

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")

See Workspace for property details.

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]

Parameters: None

Returns:

workspace · LimitedWorkspace | None

Active workspace, or None if none selected

Example:

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).

id · str

User ID

email · str

Email address

name · str

Display name

bio · str

User biography

company · str

Company name

avatar · str

Avatar image URL

verified · bool

Whether email is verified

role · str

Server role (e.g., “server:user”, “server:admin”)

PendingStreamCollaborator

Represents a pending project invitation.

id · str

Invitation ID

inviteId · str

Invite token ID

projectId · str

Project ID

projectName · str

Project name

title · str

Invitation title

role · str

Proposed role

token · str

Invitation token

invitedBy · LimitedUser

User who sent the invitation. See LimitedUser

user · LimitedUser

Invited user (you). See LimitedUser

Input Types

UserUpdateInput

UserUpdateInput(
    avatar: Optional[str] = None,
    bio: Optional[str] = None,
    company: Optional[str] = None,
    name: Optional[str] = None
)

Used with update().

Fields:

• avatar (str, optional) - Avatar image URL
• bio (str, optional) - User biography
• company (str, optional) - Company name
• name (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
)

Used with get_projects() and get_projects_with_permissions().

Fields:

• search (str, optional) - Search by project name or description
• only_with_roles (List[str], optional) - Filter by user roles
• workspace_id (str, optional) - Filter to specific workspace
• personal_only (bool, optional) - Only return personal (non-workspace) projects
• include_implicit_access (bool, optional) - Include projects with implicit access

UserWorkspacesFilter

UserWorkspacesFilter(
    search: Optional[str] = None
)

Used with get_workspaces().

Fields:

• search (str, optional) - Search by workspace name

Related Resources

OtherUserResource

Look up other users on the server

ProjectResource

Work with your projects

Authentication Guide

Learn about authentication methods

SpeckleClient

Main client documentation