Authentication and tokens

bworlds auth login
bworlds auth status

The CLI prints a one-time code and an approval URL, then waits. Open that URL on any device where you are already signed in to BWorlds. A local browser is attempted for convenience, but no loopback listener or browser on the CLI machine is required, so the flow works over SSH and in a container.

Any signed-in Builder can approve a code. The resulting Operator Session belongs to that approving Builder; platform administrator access is not required. Approval accepts a web user session only, so a personal CLI token cannot approve another machine. The CLI stores the resulting session in your user configuration directory, readable only by you. auth status shows the identity the server sees, its Workspaces, and the number of Builds you can reach. Help works without signing in.

How long an Operator Session lasts

An Operator Session renews itself for as long as you keep using it. There is no fixed deadline and no idle timeout, so an agent run that lasts hours keeps working. The CLI renews the session when it needs to, with no prompt.

Three things end one before you run bworlds auth logout, and the CLI names which one happened:

It was revoked. Changing your password ends every Operator Session you hold, on every machine. This is deliberate: a password change has to lock out whoever prompted it. Signing out of the BWorlds web app does not end them.
It was renewed elsewhere. This machine holds a credential that has already been spent. A renewal whose answer never arrived does this, as does a second program reading the same credential file. Logging in again is the whole fix.
It expired. The authentication service refused to renew it. No deadline is configured on an idle session, so this ending is rare.

Each case names its reason and ends with the bworlds auth login command that recovers, so you never have to guess whether logging in again is enough. When the service refuses without saying why, the CLI says the session ended and stops there rather than naming a cause it did not read.

A personal token is separate. It is unaffected by a password change and lasts until its expiry or until you revoke it.

Create a personal token

A BWorlds personal token lets an agent or a runner act as you. It is created from the CLI. It is not a GitHub token and is not copied from any Build setting.

bworlds auth login
bworlds auth token create \
  --name coding-agent \
  --expires-in-days 30 \
  --confirm

Token ID:  7c1d9e2f-4a5b-4c6d-8e9f-0a1b2c3d4e5f
Expires:   2026-10-07T10:02:41Z
Token:     bworlds_pat_...
Store this token now; it cannot be shown again.

Put the token in your password manager or your secret store right away. The server keeps only a one-way hash, an identifying prefix, the expiry, and usage timestamps.

Creating, listing, and revoking tokens requires a signed-in user session. A machine token cannot create a replacement or manage your other tokens.

Use a token

For a one-off process, pass it through the environment:

BWORLDS_TOKEN="$SECRET_TOKEN" bworlds auth status --json

To store it on a machine without a browser and without putting it in process arguments:

printf '%s\n' "$SECRET_TOKEN" | bworlds auth login --with-token

A plain bworlds auth login uses the same Device Approval flow on a headless machine: copy the printed code and URL to a device where you are signed in.

List and revoke

bworlds auth token list
bworlds auth token revoke CREDENTIAL_ID --confirm

Expired and revoked tokens return an authentication error. Being removed from a Workspace also removes that Workspace from every token you hold, immediately.

Sign out

bworlds auth logout

This deletes the local session on this machine only. Tokens you created stay valid until they expire or you revoke them.