API keys and surfaces¶
One tenant, one key format, five ways in. Pick the surface that matches how you work; they all drive the same sessions.
API keys¶
Keys (bk_…) are minted in the console under API keys (/app/keys),
shown once, and revocable individually. Every programmatic surface
authenticates with Authorization: Bearer <key>; the console itself uses your
GitHub OAuth session. barista login stores a key for the CLI
(~/.config/barista/key); the SDK reads BARISTA_API_KEY.
The surfaces¶
| Surface | For | Where |
|---|---|---|
CLI (barista) |
terminal workflows, scripts | reference |
Python SDK (barista_sdk) |
code, incl. an E2B-compatible adapter | reference · tutorial |
REST (/v1/*) |
anything else that speaks HTTP | the CLI reference documents the shapes |
Host API (/v1alpha1/*) |
portable apps — the open contract Cloud implements, not Cloud's own | concept |
MCP (https://mcp.barista.sh/mcp) |
agents driving sessions as tools | tutorial |
ACP (barista acp <session>) |
editors (Zed) talking to an agent inside a session | tutorial |
MCP in one paragraph¶
Point an MCP client at https://mcp.barista.sh/mcp with your bearer key and
it gets sessions as tools: session_run (one call — creates a missing worker
from a template or the platform default, wakes a parked one, runs the
command), plus sessions_list, session_create, session_exec, and
session_delete. There are deliberately no pause/resume tools: parking is
automatic and any run wakes the worker — an outer agent spawns, drives, and
reaps sessions without ever managing lifecycle.
ACP in one paragraph¶
barista acp <session> bridges your editor's Agent Client Protocol to an
agent process running inside the session, so the agent's edits happen in the
session's /work — where its commands also run — and survive pause/resume.
Your editor is the chat and diff UI; the session is the ground truth.