Skip to main content

Auth and Keys

The Hamtrax CLI authenticates every request with an API key you generate in the web app. Keys are hashed server-side (SHA-256) and shown only once at creation time -- if you lose it, you generate a new one. There is no recovery flow.

Generating a key​

  1. Sign in to hamtrax.com.
  2. Open the sidebar tools panel and choose Hamtrax CLI.
  3. Click Generate new key.
  4. Give the key a name (e.g. laptop-shack, pi-portable, agent-claude) and pick a tier:
    • basic -- read + create. Sufficient for logging contacts and creating activations.
    • elevated -- read + create + delete. Required for hamtrax contacts delete.
  5. Click Generate key. The plaintext key appears in a one-time reveal modal.
  6. Copy the key. Acknowledge the warning -- the close button stays disabled until you do.

The plaintext format is htx_live_<24-char-base32> -- e.g. htx_live_a4b6c5d7e2f3g4h5i6j7k2l3. The htx_live_ prefix is the one prepared for the GitHub Secret Scanning Partner Program; see Security for current status.

warning

The plaintext is shown once and never recoverable. If you close the modal without copying, revoke the key and generate a new one.

info

The reveal modal auto-blanks 90 seconds after it opens (mount lifetime, not idle time) as an anti-shoulder-surf measure. Copy the key first, then dismiss when you're ready.

Logging in to the CLI​

The interactive flow is the simplest:

hamtrax auth login

You'll be prompted to paste your key. The CLI calls GET /v1/whoami to validate it, then stores it.

For non-interactive contexts, pipe the key in:

echo "htx_live_xxxxxxxxxxxxxxxxxxxxxxxx" | hamtrax auth set-key

Or pass it as an argument (visible in your shell history -- prefer the pipe):

hamtrax auth set-key htx_live_xxxxxxxxxxxxxxxxxxxxxxxx

Verify:

hamtrax auth status
# source          keychain
# keyPrefix       htx_live_a4b
# callsign        N0CALL
# plan            free
# tier            basic
# nativeQsoCount  12

Resolution order​

When the CLI runs a command, it looks for a key in this order and uses the first match:

  1. HAMTRAX_API_KEY environment variable -- highest priority. This is the standard way for AI agents and CI pipelines to inject credentials.
  2. OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) -- where auth login and auth set-key store keys by default.
  3. ~/.config/hamtrax/config.json with mode 0600 -- fallback for systems where keytar is unavailable. The CLI prints a warning when auth login or auth set-key stores a key there.
  4. Error -- exits with code 3 (auth) if none of the above resolved.

Set HAMTRAX_NO_KEYRING=1 to skip step 2 entirely.

# CI / Docker / agent context
HAMTRAX_API_KEY=htx_live_xxxxxxxxxxxxxxxxxxxxxxxx hamtrax whoami --json

Tier model​

There are exactly two tiers:

TierReadCreateDelete
basicyesyesno
elevatedyesyesyes

The tier is fixed at key creation -- there's no upgrade. To change tier, generate a new key at the desired tier and revoke the old one.

A request to DELETE /v1/contacts/:qsoId with a basic key returns HTTP 403 with {"error": "tier_insufficient", "message": "...", "details": {"required": "elevated"}, "requestId": "..."}, and the CLI exits with code 5. See Command Reference and Troubleshooting.

Switching keys​

Use auth set-key again with a different value -- it overwrites the previous stored credential.

# switch from basic to elevated for a one-off cleanup session
hamtrax auth set-key htx_live_<elevated-key>
hamtrax contacts delete qso_92b1...
hamtrax auth set-key htx_live_<basic-key>   # back to read+create

For a single command, use the env var:

HAMTRAX_API_KEY=htx_live_<elevated-key> hamtrax contacts delete qso_92b1...

Logout​

hamtrax auth logout

Removes the keychain entry and any ~/.config/hamtrax/config.json fallback. Does not revoke the key on the server -- the key keeps working anywhere else it's configured. Revoke from the web app if you suspect the key has leaked.

Panic revoke​

If a key is leaked or compromised, revoke it immediately:

hamtrax auth panic-revoke

In the current CLI, this command prints the web-app revocation steps. It does not revoke the configured key server-side. Server-side revocation requires the signed-in web app because the revoke callable uses Firebase Auth.

To revoke, use the web app at any time -- useful for emergency revocation from your phone if your laptop is stolen. The server marks the key with revokedAt = now, revokedReason = 'user'; subsequent requests return HTTP 401 {"error": "key_revoked"} and the CLI exits with code 3. See Security.

tip

When in doubt, revoke. Keys are free to generate and rotation has no downside.

Storage details​

  • Keychain service name: hamtrax-cli
  • Keychain account name: default
  • Config file path: ~/.config/hamtrax/config.json (mode 0600)
  • Config file format: {"apiKey": "htx_live_..."}

The CLI never logs plaintext keys. There are no Sentry breadcrumbs, no console.log, no telemetry. See Security for the full threat model.