Skip to main content

​
Overview

specklepy uses personal access tokens to authenticate with Speckle Server.
Tokens are managed through your Speckle Server profile and can be scoped to limit permissions.

​
Get a Personal Access Token

1

Log into Speckle

Go to your Speckle Server (e.g., app.speckle.systems)
2

Access Your Profile

Click your avatar → Settings → Profile → Developer → Access Tokens
3

Create Token

Click “New Token”, give it a name and select the required scopes, then copy the token.
Store your token securely! Treat them like a password: do not post them anywhere where they could be accessed by others (e.g., public repos).

​
Token-Based Authentication

The primary way to authenticate: 
from specklepy.api.client import SpeckleClient

# Create client
client = SpeckleClient(host="app.speckle.systems")

# Authenticate with token
token = "your_token_here"  # In production, use environment variables!
client.authenticate_with_token(token)

print(f"✓ Authenticated as: {client.account.userInfo.name}")
Best practice for all environments: 
import os
from specklepy.api.client import SpeckleClient

# Get token from environment
token = os.environ.get("SPECKLE_TOKEN")
server_url = os.environ.get("SPECKLE_SERVER", "app.speckle.systems")

if not token:
    raise ValueError("SPECKLE_TOKEN environment variable not set")

# Authenticate
client = SpeckleClient(host=server_url)
client.authenticate_with_token(token)
Set the environment variable:
  • Python (.env file)
  • Linux/macOS
  • Windows (PowerShell)
  • Windows (Command Prompt)
Using python-dotenv:
pip install python-dotenv
Create .env file:
SPECKLE_TOKEN=your_token_here
SPECKLE_SERVER=https://app.speckle.systems
Load in your script:
from dotenv import load_dotenv
import os

load_dotenv()
token = os.getenv("SPECKLE_TOKEN")

​
Local Account Files (Optional)

For local development, you can use account credentials stored by Speckle desktop connectors: 
from specklepy.api.credentials import get_local_accounts, get_default_account

# Get all locally stored accounts
accounts = get_local_accounts()

for account in accounts:
    print(f"Server: {account.serverInfo.url}")
    print(f"User: {account.userInfo.name}")

# Get the default account
account = get_default_account()
if account:
    client = SpeckleClient(host=account.serverInfo.url)
    client.authenticate_with_account(account)
Local accounts are created by signing in and authenticating with any Speckle desktop connector (Revit, Rhino, Grasshopper, AutoCAD, etc.).Account files are stored in:
  • Windows: %APPDATA%\Speckle\Accounts
  • macOS: ~/.config/Speckle/Accounts
  • Linux: ~/.local/share/Speckle/Accounts

​
Account Object Structure

An Account object contains: 
# Server information
account.serverInfo.url          # "https://app.speckle.systems"
account.serverInfo.name         # "Speckle"
account.serverInfo.company      # "Speckle Systems"

# User information
account.userInfo.id             # User ID
account.userInfo.name           # "John Doe"
account.userInfo.email          # "[email protected]"

# Authentication
account.token                   # Personal access token
account.isDefault               # True/False

​
Different Speckle Servers

​
Connect to Different Servers

from specklepy.api.client import SpeckleClient

# Public Speckle server
client = SpeckleClient(host="https://app.speckle.systems")

# Custom self-hosted server
client = SpeckleClient(host="https://speckle.mycompany.com")

# Local development server (no SSL)
client = SpeckleClient(host="localhost:3000", use_ssl=False)

​
SSL Certificate Verification

For self-hosted servers with self-signed certificates: 
client = SpeckleClient(
    host="http://speckle.mycompany.com",
    verify_certificate=False  # Disable SSL verification
)
Only disable certificate verification for trusted internal servers.

​
Authentication Best Practices

Choose the authentication method that best fits your use case:
  • Development
  • Production
  • CI/CD
  • Multi-User Apps
Use environment variables or local accountsStore tokens in .env files (not committed to git) or use local account files.
from dotenv import load_dotenv
import os

# .env file approach
load_dotenv()
token = os.getenv("SPECKLE_TOKEN")
client.authenticate_with_token(token)

​
Checking Authentication Status

Verify your client is authenticated: 
# Check if authenticated
if client.account.token:
    print("✓ Authenticated")

    # Get current user info
    user = client.active_user.get()
    print(f"Logged in as: {user.name}")
    print(f"Email: {user.email}")
else:
    print("✗ Not authenticated")

​
Token Scopes

When creating a token, you can limit its permissions:
ScopeDescription
streams:readRead project data
streams:writeCreate and modify projects
profile:readRead user profile
Profile:readRead user profile
Profile:emailAccess user email
Scopes will be documented later but for now you can view all those available in the Access Token creation step:
Token Scopes
Follow the principle of least privilege - only grant the scopes your application needs.
Scopes retain the nomenclature of v2 Speckle where project is stream

​
Common Authentication Errors

Error: 403 Forbidden or Invalid tokenSolution:
  • Verify the token is correct (no extra spaces)
  • Check the token hasn’t been revoked
  • Ensure the token has the required scopes
  • Generate a new token if needed
Error: Connection refused or Failed to connectSolution:
  • Verify the server URL is correct
  • Check your internet connection
  • For local servers, ensure the server is running
  • Check firewall settings
Error: SSL: CERTIFICATE_VERIFY_FAILEDSolution:
  • For self-signed certificates, use verify_certificate=False
  • Install the certificate in your system’s trust store
  • For production, use properly signed certificates
Error: No default account foundSolution:
  • Use token authentication instead:
token = os.environ.get("SPECKLE_TOKEN")
client.authenticate_with_token(token)

​
Security Best Practices

Do:
  • Store tokens in environment variables
  • Use .gitignore to exclude .env files
  • Rotate tokens periodically
  • Use scoped tokens with minimal permissions
  • Revoke tokens when no longer needed
Don’t:
  • Commit tokens to version control
  • Share tokens between team members
  • Use tokens in client-side code (use OAuth instead)
  • Store tokens in plain text files
  • Use overly permissive scopes

​
Next Steps

Now that you’re authenticated, start sending and receiving data:

Quickstart

Build your first Speckle integration

Core Concepts

Understand Projects, Models, and Versions