ServerResource

API reference for server information and token operations in SpecklePy

Overview

The ServerResource provides methods for retrieving server information, managing API tokens, and checking server capabilities. Access it via client.server after creating your SpeckleClient.

from specklepy.api.client import SpeckleClient

client = SpeckleClient(host="https://app.speckle.systems")
client.authenticate_with_token(token)

info = client.server.get()

Methods

get()

Get detailed information about the Speckle server.

client.server.get() -> ServerInfo

Parameters: None

Returns:

info · ServerInfo

Server information object

Example:

info = client.server.get()

print(f"Name: {info.name}")
print(f"Company: {info.company}")
print(f"Description: {info.description}")
print(f"Admin Contact: {info.adminContact}")
print(f"Canonical URL: {info.canonicalUrl}")
print(f"Version: {info.version}")

# Check workspace support
if info.workspaces and info.workspaces.workspacesEnabled:
    print("✓ Workspace features enabled")

See ServerInfo for property details.

version()

Get the server version as a parsed tuple for easy version comparison.

client.server.version() -> Tuple[Any, ...]

Parameters: None

Returns:

version · Tuple

Version tuple in format (major, minor, patch) or (major, minor, patch, tag, build) for pre-release versions

Example:

version = client.server.version()

print(f"Version: {version}")
# Output: (3, 0, 0) for stable or (3, 0, 0, 'alpha', 123) for pre-release

# Version comparison
major_version = version[0]
if major_version >= 3:
    print("Server supports v3 features")
elif major_version == 2:
    print("Server uses v2 features")
else:
    print("Legacy server version")

apps()

Get the list of apps registered on the server.

client.server.apps() -> Dict

Parameters: None

Returns:

apps · Dict

Dictionary of registered apps

Example:

apps = client.server.apps()

for app in apps:
    print(f"\nApp: {app['name']}")
    print(f"  Description: {app['description']}")
    print(f"  Trust by default: {app['trustByDefault']}")
    print(f"  Author: {app['author']['name']}")
    if app.get('logo'):
        print(f"  Logo: {app['logo']}")

See App for property details.

create_token()

Create a new personal API token programmatically.

client.server.create_token(
    name: str,
    scopes: List[str],
    lifespan: int
) -> str

Parameters:

name · str · required

A descriptive name for the token

scopes · List[str] · required

List of scope names to grant

lifespan · int · required

Token lifespan in seconds

Returns:

token · str

The newly created token string

The token is only shown once when created. Store it securely immediately!

Example:

# Create a token with specific scopes
token = client.server.create_token(
    name="CI/CD Pipeline Token",
    scopes=["streams:read", "streams:write", "profile:read"],
    lifespan=86400 * 30  # 30 days in seconds
)

print(f"New token created: {token[:10]}...")
print("Store this token securely - you won't see it again!")

# Save to secure location (e.g., secrets manager, env file)
import os
with open('.env', 'a') as f:
    f.write(f'\nSPECKLE_TOKEN={token}\n')

Common Scopes:

• streams:read - Read project/stream data
• streams:write - Write project/stream data
• profile:read - Read user profile
• profile:email - Access user email
• profile:delete - Delete user profile
• users:read - Read other user information
• users:email - Access other user emails
• tokens:read - Read token information
• tokens:write - Create/revoke tokens

revoke_token()

Revoke (delete) a personal API token.

client.server.revoke_token(token: str) -> bool

Parameters:

token · str · required

The token string to revoke

Returns:

success · bool

True if the token was successfully revoked

Example:

# Revoke a token
token_to_revoke = "abc123def456..."

success = client.server.revoke_token(token_to_revoke)

if success:
    print("✓ Token successfully revoked")

You can only revoke tokens that belong to your authenticated account.

Types

ServerInfo

Represents detailed information about a Speckle server.

name · str

Server name

company · str

Company name

description · str

Server description

adminContact · str

Admin contact email

canonicalUrl · str

Server canonical URL

version · str

Server version string (e.g., “3.0.0”)

scopes · List[Scope]

Available API scopes - name (str) - Scope name - description (str) - Scope description

authStrategies · List[AuthStrategy]

Available authentication strategies - id (str) - Strategy ID - name (str) - Strategy name - icon (str, optional) - Icon URL

workspaces · WorkspacesInfo

Workspace feature information - workspacesEnabled (bool) - Whether workspaces are enabled

App

Represents an application registered on the Speckle server.

id · str

App ID

name · str

App name

description · str

App description

termsAndConditionsLink · str

Terms and conditions URL

trustByDefault · bool

Whether app is trusted by default

logo · str

App logo URL

author · dict

App author information - id (str) - Author user ID - name (str) - Author name - avatar (str, optional) - Author avatar URL

FAQ

How do I check if a server supports specific features?

Use get() to retrieve server information and check capabilities:

info = client.server.get()

# Check workspace support
has_workspaces = (
    info.workspaces and
    info.workspaces.workspacesEnabled
)

# Check available scopes
scope_names = [scope.name for scope in info.scopes]
has_automation = "automate:report-results" in scope_names

How do I compare server versions in my code?

Use the version() method which returns a comparable tuple:

version = client.server.version()
major, minor = version[0], version[1]

# Check for minimum version
if (major, minor) >= (3, 0):
    print("Server meets minimum version 3.0")

# Version-specific behavior
if major >= 3:
    # Use v3 API features
    pass
elif major == 2:
    # Use v2 API features
    pass
else:
    raise ValueError("Unsupported server version")

What scopes should I request for my token?

Request only the scopes you need:

• Read-only access: ["streams:read", "profile:read"]
• Basic read/write: ["streams:read", "streams:write", "profile:read"]
• Automation/CI: ["streams:read", "streams:write", "profile:read", "tokens:write"]
• Admin operations: Check server’s available scopes with get()

Use client.server.get().scopes to see all available scopes and their descriptions.

How long should I set my token lifespan?

Token lifespan recommendations:

• Development/testing: 7-30 days (604800 - 2592000 seconds)
• CI/CD pipelines: 90-365 days (7776000 - 31536000 seconds)
• Production services: 365 days, with rotation strategy
• Temporary access: 1-7 days (86400 - 604800 seconds)

# Common lifespans
ONE_DAY = 86400
ONE_WEEK = 604800
ONE_MONTH = 2592000
ONE_YEAR = 31536000

token = client.server.create_token(
    name="My Token", scopes=scopes, lifespan=ONE_MONTH
)

Can I list all my existing tokens?

The ServerResource doesn’t provide a method to list tokens directly. To manage your tokens:

1. Log in to the Speckle web interface
2. Go to your profile settings
3. Navigate to “Personal Access Tokens”
4. View and manage all your tokens there

Alternatively, use the ActiveUserResource methods if available in your version.

What happens if I create a token with invalid scopes?

The server will reject the request if you specify scopes that don’t exist or that you don’t have access to. Always check available scopes first:

# Get available scopes
info = client.server.get()
available_scopes = {scope.name for scope in info.scopes}

# Validate your desired scopes
desired_scopes = ["streams:read", "streams:write", "profile:read"]

if all(scope in available_scopes for scope in desired_scopes):
    token = client.server.create_token(
        name="My Token",
        scopes=desired_scopes,
        lifespan=2592000
    )
else:
    print("Some requested scopes are not available")

Related Resources

SpeckleClient

Main client documentation

ActiveUserResource

User profile operations