05 API Key Management

API Key Management

The key is a secret and a long-lived one. It is deliberately kept outside the configuration, the code and every release archive.

---

Where the key lives

/etc/abuseipdb/.abuseipdb.key      mode 600 root:root
/etc/abuseipdb/reporter.conf       mode 600, contains api_key_file = /etc/abuseipdb/.abuseipdb.key

The key file contains one line — the key itself, plus a trailing newline. It is created by install.sh or by abuseipdb-report --setup, written atomically (temp file + rename), and never rewritten by an upgrade if it already exists.

Resolution order

The reporter resolves the key at runtime, in this order:

#	Source	Persisted?	Typical use
1	--api-key KEY	no (one-off)	manual checks, CI smoke tests
2	ABUSEIPDB_API_KEY or ABUSEIPDB_KEY env	no	containers, configuration management
3	key file (api_key_file, ABUSEIPDB_KEY_FILE, default /etc/abuseipdb/.abuseipdb.key)	yes	the normal production source
4	legacy api_key in reporter.conf	deprecated	old installations; migrate it
5	interactive prompt	saves to the key file	first run by a human

The first non-empty source wins. If none is available:

• on a terminal → prompt once, validate lightly (length 80, hex) and save to the key file;
• under systemd/cron → log a clear error and exit with code 2 instead of hanging.

First run: the wizard

sudo /usr/local/sbin/abuseipdb-report --setup

No AbuseIPDB API key found. Get one at https://www.abuseipdb.com/account/api
The key is stored in /etc/abuseipdb/.abuseipdb.key (mode 600) and is preserved across updates.
Enter your AbuseIPDB API key:            # input is hidden
API key saved to /etc/abuseipdb/.abuseipdb.key

The installer does the same when called without --api-key on a terminal. Non-interactive installations pass --api-key, --api-key-file, or ABUSEIPDB_API_KEY.

Inspecting and moving keys

# Which source is in use? Prints the source and a MASKED key (3078ab...0072)
/usr/local/sbin/abuseipdb-report --key-status

# Move a legacy api_key out of reporter.conf into the key file; blanks the config line
/usr/local/sbin/abuseipdb-report --migrate-key

# Validate the key online (one /check request)
/usr/local/sbin/abuseipdb-report --check-key

The installer migrates a legacy api_key automatically and blanks the config line:

# before
[abuseipdb]
api_key = <secret>
# after
[abuseipdb]
api_key_file = /etc/abuseipdb/.abuseipdb.key
api_key =

Rotation

# 1. generate a new key at https://www.abuseipdb.com/account/api
# 2. write it atomically (do not put it in shell history)
install -m 600 /dev/stdin /etc/abuseipdb/.abuseipdb.key <<< "NEW_KEY"
# 3. verify
/usr/local/sbin/abuseipdb-report --check-key

No restart is needed: the key is read on every run. Revoke the old key in the AbuseIPDB account after the first successful run with the new one.

What never happens

• the key is not written to logs (--key-status masks it; the reporter logs 3078ab...0072);
• it is not part of reporter.conf, the release tarball, updater.json or git (.gitignore contains *.key);
• the installer does not overwrite an existing key file on upgrade;
• the updater snapshots the key file before running the installer and restores it if the installer fails or the file disappears;
• --api-key on the command line is convenient but visible in ps/history — prefer the file.

Multiple hosts / fleet

• each host has its own key file; the same key may be shared, but per-host keys make revocation easier;
• deployment automation writes the key file once (install -m 600) and never touches it again;
• install.sh honours --key-file PATH when you keep secrets on a separate volume;
• the key is never needed by the fail2ban action, so the queue helper runs without secrets.

Troubleshooting

Symptom	Cause	Fix
--key-status says “not configured”	no key in any source	--setup, installer prompt, env or key file
reporter logs No AbuseIPDB API key found under systemd	no key and no terminal	create the key file or pass ABUSEIPDB_API_KEY in the unit
401 from the API	revoked/wrong key	replace the key file, --check-key
config still has api_key	legacy install	--migrate-key

---

Next: Self-Update · Configuration Reference · Troubleshooting