Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(security): document recovering from a lost admin key (#1805)
Yudhi Armyndharis13919722a551
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1f7f3a548..99de01f6f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -78,6 +78,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Documentation+- Document how to recover a lost admin API key without revoking the other keys.- The integration docs say `integration_delivery_failures` holds only failed inbound deliveries.- The webhook runbook documents the ADMIN delivery-failure redrive and no longer says failed deliveries retry on their own.diff --git a/docs/04-security-design.md b/docs/04-security-design.mdindex 3bf6c4785..4b98a92bf 100644--- a/docs/04-security-design.md+++ b/docs/04-security-design.md@@ -100,6 +100,57 @@ private-network proxy sidecar works). The destinations of caller-supplied URLs fstill vetted by the SSRF guard. Reading the proxy (`GET /api/sessions/:sessionId/proxy`) returns onlythe masked host, type and a `hasCredentials` flag.+### Recovering a lost admin key++Keys are stored as one-way hashes, so a lost key cannot be read back from the database: it is either+found where it was saved, or replaced. Try these in order. If every key stopped working at once after+`API_KEY_PEPPER` was set or changed, follow the pepper recovery in §4.4 instead.++1. **The bootstrap key file or `API_MASTER_KEY`.** The key seeded on first boot is kept in+ `data/.api-key` (or the `BOOTSTRAP_KEY_FILE` path) until that key is no longer active (revoked,+ expired or deleted). While the file holds a live key, the startup banner ends with+ `(full key in <path>)`. Read it with `cat data/.api-key`, or with+ `docker compose exec openwa-api cat /app/data/.api-key` on the compose deployment. If+ `API_MASTER_KEY` was set before first boot, the seeded key is that value, and it still works+ unless it was revoked since.++2. **Another ADMIN key.** Any active, unexpired `admin` key without `allowedSessions` or+ `allowedChats` can manage keys: mint a replacement with `POST /api/auth/api-keys`+ (`{"name": "Admin", "role": "admin"}`; the raw key is returned once, in `apiKey`), then revoke the+ lost one with `POST /api/auth/api-keys/:id/revoke`, or do both from the dashboard's API Keys page.++3. **Replace the key in the main database.** With no usable ADMIN key left, give the lost key's row+ a new key; every other key keeps working. Stop the instance and copy the main database aside. Then+ generate a key and its hash with the gateway's own hash function and configuration (process env,+ `.env` and `data/.env.generated`, so the same `API_KEY_PEPPER`). Run it from the gateway's install+ directory, the one holding `dist/` and `data/`, so it reads that install's configuration:++ ```bash+ GEN="require('./dist/config/load-env'); const key = 'owa_k1_' + require('crypto').randomBytes(32).toString('hex'); console.log('key:', key); console.log('prefix:', key.slice(0, 12)); console.log('hash:', require('./dist/modules/auth/api-key-hash').hashApiKey(key, process.env.API_KEY_PEPPER))"+ node -e "$GEN" # source install, after npm run build+ docker compose run --rm --no-deps openwa-api node -e "$GEN" # compose deployment+ ```++ Find the row and write the new hash and prefix into it. The main database is+ `MAIN_DATABASE_NAME`, `data/main.sqlite` by default; on the compose deployment run `sqlite3` as+ `docker compose run --rm --no-deps openwa-api sqlite3 /app/data/main.sqlite "..."`:++ ```bash+ sqlite3 data/main.sqlite "SELECT id, name, keyPrefix, isActive, expiresAt FROM api_keys WHERE role = 'admin'"+ sqlite3 data/main.sqlite "UPDATE api_keys SET keyHash = '<hash>', keyPrefix = '<prefix>', isActive = 1, expiresAt = NULL, allowedIps = NULL, allowedSessions = NULL, allowedChats = NULL WHERE id = '<id>'"+ ```++ Start the instance and use the new key. The update also clears the row's revoked state, expiry,+ and IP, session and chat restrictions, so it can manage keys again; narrow it afterwards through+ the API if it carried any. The old key no longer authenticates.++4. **Reset the key table.** When no row is worth keeping, empty `api_keys` as the pepper recovery in+ §4.4 describes: the next boot seeds a new ADMIN key (from `API_MASTER_KEY` when set) and prints+ it once. Every other key must then be re-issued.++Keys live in each node's own main database ([13 - Horizontal Scaling](./13-horizontal-scaling.md)),+so on a multi-node deployment the recovery applies only to the node it ran on.+## 4.3 IP WhitelistingIP whitelisting adds an extra security layer by restricting API key access to specific IP addresses.diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.mdindex 490326c3f..b6c9ce285 100644--- a/docs/11-operational-runbooks.md+++ b/docs/11-operational-runbooks.md@@ -955,8 +955,8 @@ curl -s -X POST -H "X-API-Key: <an-existing-key>" http://localhost:2785/api/auth> `main.sqlite` carries the hashed API keys and audit log; `.api-key`, when retained by the original> installation, carries the plaintext bootstrap admin key. After restore, verify that both expected files> were present in the archive and that the client is using the original plaintext key. Re-running backup-> after the source state or key has already been lost cannot recover it; use an older valid archive or the-> documented credential-recovery procedure instead.+> after the source state or key has already been lost cannot recover it; use an older valid archive or+> [recover the admin key](./04-security-design.md#recovering-a-lost-admin-key) instead.**Verification:**diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.mdindex aa205847c..aafa770ec 100644--- a/docs/12-troubleshooting-faq.md+++ b/docs/12-troubleshooting-faq.md@@ -1406,6 +1406,10 @@ The shipped script also covers `main.sqlite`, the selected data store, whatsapp-`BAILEYS_AUTH_DIR` (default `./data/baileys`), media, plugin packages/state, and generated secrets. Applyretention/encryption to completed archives externally; see the [backup and restore runbooks](./11-operational-runbooks.md#runbook-database-backup).+**Q: I lost the admin API key. How do I get back in?**++> A: Keys are stored hashed, so the database cannot give it back. Check `data/.api-key` (or `BOOTSTRAP_KEY_FILE`) and the `API_MASTER_KEY` value the instance was first started with, then use another unscoped ADMIN key to mint a replacement. With neither, stop the instance and write a new key's hash into the lost key's row in the main database, which keeps every other key working. The steps are in [Recovering a lost admin key](./04-security-design.md#recovering-a-lost-admin-key).+### Webhook Questions**Q: What events can I subscribe to?**