Authentication

The CLI authenticates you once through the browser and stores the credentials locally. CI pipelines, scripts, and agents skip the browser with a token or a long-lived API key.

Log in

boxd auth login                # opens browser for one-time device login
boxd auth                      # show your identity and the orgs you belong to
boxd auth logout               # remove stored credentials

Any command that needs auth auto-starts the login flow if no credentials are found, so on a fresh install you can run any command and log in on the way.

Tokens

Authenticate a single invocation with a token, overriding stored credentials:

boxd --token=<TOKEN> machine list      # pass token directly
BOXD_TOKEN=<TOKEN> boxd machine list   # or via env var

API keys

For CI pipelines, scripts, or agent integrations where the browser login flow is not an option, mint long-lived API keys under boxd auth keys. The raw value is shown only once, at creation time.

boxd auth keys create NAME                            # mint a new key, raw value to stdout
boxd auth keys create NAME --expires-in-secs=86400    # with an expiry (1 day in this example)
boxd auth keys create NAME --org myorg                # fence the key to a specific org
boxd auth keys create NAME --kind org                 # userless service credential (org admin only)
boxd auth keys list                                   # id, name, prefix, org, kind, last-used, expires (alias: ls)
boxd auth keys remove ID                              # revoke a key (alias: rm)

Every key is fenced to one org and never grants account-wide access. Without --org, the key is fenced to your active org context. --kind member (the default) acts as you within that org. --kind org is a userless service credential limited to the org’s shared machines, and creating one requires org admin. keys create writes the raw bxd_… value to stdout, while the warning, id, and expiry go to stderr. To put it straight into a GitHub secret without copy and paste:

KEY=$(boxd auth keys create "gh-actions deploy owner/repo")
gh secret set BOXD_API_KEY --repo owner/repo --body "$KEY"

The key never lands in shell history or scrollback. --json mode is also available for scripting:

Command	JSON shape
`auth keys create --json`	`{"id", "api_key", "expires_at"}` (`expires_at: 0` = no expiry)
`auth keys list --json`	`[{"id", "name", "prefix", "org", "kind", "last_used", "expires"}, …]`

Org context

Every account works in an org context, and your personal account counts as an organization of its own. Your active context decides which org a new machine is billed to and which machines list and connect see.

boxd auth                        # identity + the orgs you belong to (active context marked)
boxd auth switch acme            # work in the "acme" org context (multi-word names need no quotes)

The active org context is a per-device selection. boxd auth switch writes it locally, and each surface (this CLI, the web console, other devices) keeps its own. Your own org is a normal org in the list, so you switch back to it by name like any other, and an unset context shows as (default). To run one invocation in a specific org without switching, pass --org. Sharing machines with the org happens on the machine side. See Organizations in the command reference.

Next step

You are logged in. Head to the full command reference.

Getting started

Guides

Use cases

References

Authentication

Log in

Tokens

API keys

Org context

Next step

​Log in

​Tokens

​API keys

​Org context

​Next step

Log in

Tokens

API keys

Org context

Next step