Python SDK

The official Python SDK for Burdenoff Workspaces provides async/await access to the full GraphQL API.

Install

pip install workspaces-sdk

Development install:

git clone https://github.com/algoshred/workspaces-sdk-python.git
cd workspaces-sdk-python
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"

Environment selection

The SDK endpoint defaults to production. Select a different environment by passing the appropriate endpoint in WorkspacesConfig, or set BURDENOFF_ENV in your shell:

Environment	Workspace endpoint	Global endpoint
prod (default)	https://graphqlworkspaces.burdenoff.com/workspaces/graphql	https://graphql.burdenoff.com/global/graphql
alpha	https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql	https://alphagraphql.burdenoff.com/global/graphql
local	http://localhost:4003/workspaces/graphql	http://localhost:4000/global/graphql

Set BURDENOFF_ENV=local|alpha|prod in your shell if your app consumes it to choose endpoints, or pass them explicitly to WorkspacesConfig.

Quick start

import asyncio
from workspaces_sdk import WorkspacesSDK, WorkspacesConfig

async def main():
    sdk = WorkspacesSDK(WorkspacesConfig(
        workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
        global_endpoint="https://graphql.burdenoff.com/global/graphql",
    ))

    # Sign in with email/password
    auth = await sdk.auth.sign_in("[email protected]", "password")
    print(f"Signed in as {auth['user']['fullName']}")

    # List workspaces
    workspaces = await sdk.workspace.list_workspaces()
    for ws in workspaces:
        print(f"Workspace: {ws['name']} ({ws['slug']})")

    # List projects in the first workspace
    projects = await sdk.workspace.list_projects(workspaces[0]["id"])
    for p in projects:
        print(f"Project: {p['name']} — {p['status']}")

    await sdk.close()

asyncio.run(main())

Configuration

from workspaces_sdk import WorkspacesConfig

config = WorkspacesConfig(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",

    # OAuth2 (optional, for device code / PKCE / client credentials flows)
    oidc_issuer="https://auth.burdenoff.com",
    client_id="workspaces-cli",
    client_secret=None,           # Only for client credentials flow
    redirect_uri=None,            # Only for PKCE flow

    # Pre-existing tokens (optional)
    api_key=None,
    access_token=None,
    refresh_token=None,
    workspace_token=None,

    timeout=30.0,                 # Request timeout in seconds
    auto_refresh=True,            # Auto-refresh tokens before expiry
    on_token_refresh=None,        # Callback for external token persistence
)

Authentication flows

Email / password

auth = await sdk.auth.sign_in("[email protected]", "password")

Device code (CLI / headless)

device = await sdk.auth.start_device_code_flow()
print(f"Visit {device['verification_uri_complete']} and enter code {device['user_code']}")
# SDK polls automatically until the user authorizes

PKCE (browser-based)

challenge = sdk.auth.build_authorization_url()
# Redirect user to challenge["url"]
# After callback:
result = await sdk.auth.exchange_auth_code(code, challenge["codeVerifier"])

Client credentials (machine-to-machine)

config = WorkspacesConfig(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",
    client_id="my-service",
    client_secret="secret",
)
sdk = WorkspacesSDK(config)
# Tokens are obtained automatically on first request

Modules

All methods are async. Access each module as a property on the WorkspacesSDK instance.

Module	Property	Description
Auth	sdk.auth	Sign in/up, sign out, token refresh, device code, PKCE, client credentials
Workspace	sdk.workspace	Workspace and project CRUD
Conversation	sdk.conversation	Channels and messaging
File	sdk.file	File operations
Tag	sdk.tag	Tag management
Group	sdk.group	Group and team operations
RBAC	sdk.rbac	Permission checks
Billing	sdk.billing	Billing queries
Scheduler	sdk.scheduler	Job scheduling
Webhook	sdk.webhook	Webhook management
Notification	sdk.notification	Notification channels

Error handling

from workspaces_sdk.errors import (
    WorkspacesError,
    AuthenticationError,
    AuthorizationError,
    NetworkError,
    ValidationError,
    RateLimitError,
    DeviceCodeExpiredError,
    DeviceCodeDeniedError,
)

try:
    await sdk.auth.sign_in("[email protected]", "wrong")
except AuthenticationError:
    print("Invalid credentials")
except NetworkError:
    print("Could not reach the API")
except WorkspacesError as e:
    print(f"SDK error: {e}")

Development

# Create virtual environment
python -m venv venv && source venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

# Format
black src/ tests/ examples/
isort src/ tests/ examples/

# Lint
flake8 src/ tests/ examples/
mypy src/

# Test
pytest
pytest --cov=workspaces_sdk --cov-report=html

# Build
python -m build

Source

• Repository: github.com/algoshred/workspaces-sdk-python
• Package: workspaces-sdk on PyPI

Next steps

• Node SDK
• GraphQL API
• CLI reference