Every request to Spectron must carry a context or management API key as an HTTP Bearer token:
There are no session cookies and no OAuth on the data plane. Authentication is stateless: the server validates the key, resolves the principal, and enforces scope before handling the request.
Principal types
| Principal | Typical scope floor | Capabilities |
|---|---|---|
| Management | Unrestricted | Context lifecycle, key provisioning, management REST |
| Agent | Org / agent / user paths | Read and write within the effective scope |
| Supervisor | Org-wide read | Read across the org; limited write (for example reflection persist) |
See Principals and Scope as security boundary.
Bootstrapping the first keys
On a fresh install, run bootstrap once (via Docker or your operator runbook):
Stdout prints SPECTRON_MANAGEMENT_API_KEY and SPECTRON_API_KEY plus the new Context id. Store them immediately; secrets are not shown again.
Additional Context keys are minted via:
Management REST:
POST /api/v1/contexts/{id}/keys/{name}CLI:
spectrond keys generate-key(CLI reference)
Environment variables (clients)
The public spectron CLI and generated SDKs expect:
| Variable | Purpose |
|---|---|
SPECTRON_URL | Base URL (for example http://localhost:9090) |
SPECTRON_API_KEY | Context-scoped end-user key |
SPECTRON_CONTEXT_ID | Context id in the path |
Harness adapters also accept SPECTRON_BASE_URL and SPECTRON_CONTEXT per package READMEs in the Spectron repo clients/ tree.
MCP
MCP clients (Claude Desktop, Cursor, Claude Code) send the same Bearer token in the MCP transport config (Authorization: Bearer …). Run spectron mcp to print an install snippet.
Key rotation
Rotate a key in place without changing its id, principal binding, or grants:
The response includes a new secret (shown once). The previous secret stops working immediately — there is no overlap window. Omit ttl_seconds to inherit the key’s current expiry; pass it to reset expiry from now.
Alternatively, mint a replacement key and delete the old one — see API keys and delegation.