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 registered with the GitHub Secret Scanning Partner Program (status: pending registration -- see Security) so accidental commits to GitHub trigger automatic alerts.

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
# Key prefix: htx_live_a4b
# Tier:       basic
# Callsign:   N0CALL

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 without a Secret Service. The CLI prints a one-time stderr warning when it falls back.
  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 one in your keychain.

# 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. Use auth panic-revoke if you suspect the key has leaked.

Panic revoke​

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

hamtrax auth panic-revoke

This calls the same revoke endpoint the web app uses against the currently configured key. 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.

You can also revoke from the web app at any time -- useful for emergency revocation from your phone if your laptop is stolen. 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: the key prefix (first 12 chars of the plaintext)
  • 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.