Workspace Auth Tokens

Phase: 30.1 Source: workspace-server/internal/auth/workspace_tokens.go

Overview

Each workspace in Molecule AI has a unique, cryptographically random bearer token used for agent-to-platform authentication. Tokens are scoped to a single workspace and carry no permissions beyond that workspace's resources.

Token Properties

Bootstrap Behavior

When the workspace server starts or reconnects, agents bootstrap using their workspace token. If the token validation service is temporarily unavailable (e.g., during a migration or network partition), the bootstrap fails open — the agent is not blocked from starting, but operates in a restricted mode until the service is confirmed available.

This design avoids a class of availability failures where a single infrastructure outage prevents all agent restarts.

Architecture

Agent → Workspace Token (raw) → workspace-server
                              → lookup hashed token in workspace_auth_tokens
                              → resolve workspace ID → authorize request

Security Considerations

• Raw tokens are secrets — log them only in transient debug contexts, never in structured logs.
• Tokens are hashed at rest — the plaintext never appears in the database; only SHA-256 hashes are stored.
• Cross-workspace isolation — tokens carry no org-level privileges; workspace-scoped only.
• Lazy bootstrap — tokens are validated on first request, not eagerly on agent startup, to minimize unnecessary database round-trips.

Related

• Org API Keys — org-level full-admin tokens
• REST API Reference — all endpoints accepting workspace tokens
• External Agent Registration — onboarding remote agents with workspace tokens