> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Log in once through the browser, or mint API keys for CI, scripts, and agents.

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](#api-keys).

## Log in

```bash theme={"theme":"github-dark"}
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:

```bash theme={"theme":"github-dark"}
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.

```bash theme={"theme":"github-dark"}
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:

```bash theme={"theme":"github-dark"}
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.

```bash theme={"theme":"github-dark"}
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](/cli/commands#organizations) in the command reference.

## Next step

You are logged in. Head to the full [command reference](/cli/commands).