Authentication

TokenBot authenticates every request with a cryptographic signature. There is no password to type and no bearer token to leak.

How it works

When you run tokenbot init, the CLI generates a secp256k1 keypair. The public key is registered against your account; the private key is encrypted with a passphrase you choose and stored locally in ~/.tokenbot/config.json.

From then on, every request carries four headers:

Header	Contents
`x-tb-pubkey`	your registered public key
`x-tb-timestamp`	Unix milliseconds — the server tolerates ±60s of clock skew
`x-tb-nonce`	16 random bytes, hex — replay window is 10 minutes
`x-tb-sig`	secp256k1 signature over the canonical string

The signature covers:

METHOD\n
path\n
timestamp\n
nonce\n
sha256Hex(body || '')

Because the signature covers the method, path, timestamp, nonce and a hash of the body, a captured request cannot be replayed against a different endpoint, altered in transit, or reused after its window closes.

Your private key never leaves your machine. It is not sent during registration, and it is not sent with any request — only the signature it produces.

Registering an identity

tokenbot init --label "work laptop"
tokenbot whoami

init binds a new keypair to an existing account — it does not create one. TokenBot is currently early access; join the waitlist at site.tokenbot.com.

You can register more than one identity — one per machine is the usual pattern — each with its own label. Use --config (or TOKENBOT_HOME) to keep separate identities side by side:

tokenbot --config ~/.tokenbot-work whoami

tokenbot logout deletes the local config and encrypted key store.

Your passphrase

The private key is encrypted at rest under the passphrase you set during init, using scrypt for key derivation and an authenticated secretbox for encryption.

There is no recovery path. If the passphrase is lost, the key cannot be decrypted — register a new identity with tokenbot init and re-bind it to your account.

API keys

API keys are for your own integrations against the REST and GraphQL APIs — scripts, dashboards you build, CI jobs. The CLI itself never uses them.

tokenbot apikey create --name "analytics integration" --env live
tokenbot apikey list
tokenbot apikey revoke <id>

The secret is shown exactly once at creation. --env accepts live or test.

See API Keys.

What happened to passwords, OAuth, passkeys and 2FA?

Those belonged to the web dashboard, which was retired when TokenBot moved to a CLI-first model. There is currently no password login, no OAuth provider flow, no passkey registration and no TOTP enrolment — and no CLI command for any of them.

The signed-request scheme above replaces them. It is phishing-resistant for the same reason passkeys are — a signature is bound to the exact request and cannot be replayed elsewhere — without depending on a browser.

Troubleshooting

“no CLI identity configured” — run tokenbot init, or check you aren’t pointing at a different --config / TOKENBOT_HOME.

Signature or timestamp rejected — the server rejects stale timestamps. If requests start failing after your machine has slept or the clock has drifted, sync it and retry.

See CLI Troubleshooting.