boxctl
DocsSign in

API tokens

Personal tokens let the boxctl CLI act as you. Create, use, and revoke them here.

A personal API token authenticates the boxctl CLI as you. Tokens are managed on the API tokens page of the dashboard.

Creating a token

  1. Open API tokens.
  2. Give the token a name that tells you where it will live, such as laptop or ci.
  3. Click Create.

The token value is shown exactly once, immediately after creation. Copy it then. boxctl does not store the plaintext value and cannot show it again. If you lose it, revoke it and create a new one.

Using a token

You usually don't need to create one: boxctl login opens a page here where one click makes a token for that computer, labeled cli: <its hostname>, which appears in the list like any other. Tokens you create by hand are for scripts and CI jobs:

BOXCTL_TOKEN=... boxctl ls     # every command uses the variable, no login needed
boxctl login --paste           # or save it: paste at the hidden prompt
pbpaste | boxctl login         # or pipe it in

See [Command line](/docs/cli) for the rest.

## What a token can do

A token is scoped to your own boxes. It can list, create, connect to,
pause, resume, back up, and destroy boxes that belong to you, and
nothing else. The scoping is enforced by the backend, not just by the
CLI.

## Revoking a token

Click **Revoke** next to a token on the [API tokens](/dashboard/tokens)
page. Revocation takes effect immediately. Any CLI still holding that
token will start getting authentication errors.

Revoke a token whenever the machine it lived on is retired, lost, or
shared, or whenever you are not sure where a copy of it ended up.