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. In the setup steps, click step 2 Generate key. The whole row is the button -- the step list slides out to the left and the form slides in from the right, in the space the steps were using. Your existing keys stay on screen in the API keys panel the whole time, and that panel's own Generate key button opens the same form.
  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 the form's Generate key button. 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.

Cancel slides the setup steps back and discards anything you had typed -- the step is entered, not remembered.

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.