Auth & tokens

Two kinds of credential — your interactive login and a workspace API key — where they live, and what's safe to commit.

The edge validates exactly one thing: a bearer token. But that token is minted two ways, for two different principals. Keeping the two jobs separate is what makes Beamd both simple and safe.

Two kinds of credential

	Interactive login (`beamd login`)	Workspace API key
Principal	you (the user)	a workspace (one org)
Reaches	every org you belong to	exactly one workspace
Scope	per-command / `.beamd` / default — no re-login	fixed; the key is the scope
Lifetime	session-grade: refreshable, revoked on logout	long-lived, named, independently revocable
Acquired via	browser / device-code (hosted) or `--token` (self-host)	dashboard → "Create API key", shown once
Used by	humans at a terminal	CI, agents, `--config` files

The rule of thumb: broad ⇒ ephemeral and human; durable ⇒ narrow and org. Never broad-and-durable (the classic leaked-PAT footgun), never narrow-and-interactive (the per-org-login annoyance).

The CLI exposes exactly one interactive flow. On a hosted edge that's device-code: you press enter, approve in the browser, and the variety of auth methods (Google, GitHub, magic-link, SSO, MFA) lives in the browser — the CLI never touches a password. Headless? Use an API key.

Where credentials live

beamd login saves an account under ~/.beamd/, one file per edge, keyed by server host:

~/.beamd/
  config                        # global: current account + naming defaults
  accounts/
    beamd.run.yaml               # hosted → session + cached orgs + default scope
    edge.mycompany.com.yaml     # self-host → static token
  agents/
    beamd.run.sock               # one detached agent per account

A hosted account stores a session token plus your cached org list; a self-hosted account stores the static token your operator issued. Either way, the file is yours (0600) and never leaves your machine.

Automation with `--config`

CI and embedded apps shouldn't touch your personal account store. Pass a dedicated config file with a workspace API key instead — it bypasses accounts, scope selection, and the project ladder entirely:

# my-app-beamd.yaml — referenced via --config my-app-beamd.yaml
server: tunnel.example.com:443
token: <workspace API key>

No beamd default, no --scope, no device-code — the key's scope is fixed. Full embedding guidance is in Embed in your app.

What's safe to commit

A .beamd file references an edge and scope — never a token — so commit it freely. Tokens live only in ~/.beamd/ (your login) or in a --config file you keep out of version control (automation). If a login leaks it's broad but ephemeral and revocable; if an API key leaks, one workspace is the ceiling.

Self-hosted (OSS) edges

A self-hosted edge has no org concept, so auth is just the static token your operator issued:

beamd login --server edge.mycompany.com --token <token>