CI/CD

API tokens

Create long-lived tokens so the CLI can authenticate from CI, build servers, and other non-interactive environments.

What are they for?

API tokens exist so the Handoff CLI can sign in without a browser. They are the credential CI systems use when they run handoff pull or handoff run.

Create a token

  1. Go to Organization → API keys
  2. Click Create token, give it a descriptive name (e.g. github-actions-production), and optionally set an expiry
  3. Copy the token immediately; it's shown once and never again

Tokens are prefixed hnd_ so they're easy to spot in logs and secret scanners. Store the full token in your CI provider's secret manager (GitHub Actions secrets, etc.); never commit it.

Under the hood each token carries its own X25519 keypair: the dashboard seals a copy of the org key to that keypair at creation time, and the server stores only a SHA-256 hash of the token string plus the sealed box. A leaked server database does not let anyone decrypt your secrets. See the security model for the full picture.

Use a token

Pass it to the CLI via --token or the HANDOFF_TOKEN environment variable:

HANDOFF_TOKEN=hnd_xxxxxxxx handoff run \
  --env production \
  -- ./start.sh

Or inline:

handoff run --env production --token hnd_xxxxxxxx -- ./start.sh

See handoff run for the full flag list.

Rotate and revoke

  • A token's last-used time is visible on the API keys page; use it to find stale credentials.
  • Click Revoke on any token to invalidate it immediately. In-flight requests with that token start failing on the next call.
  • If you think a token leaked, revoke first, then rotate; the two actions are independent.

Plan limits

The CLI is free on every plan. Free organizations can hold up to 3 active CI/CD tokens at a time, enough for one or two pipelines. Team is unlimited. If you hit the cap, revoke an unused token from the API keys page or upgrade on the pricing page.

PreviousOverviewNextGitHub Actions