Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(security): document recovering from a lost admin key (#1805)

Yudhi Armyndharis13919722a551
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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 f
still vetted by the SSRF guard. Reading the proxy (`GET /api/sessions/:sessionId/proxy`) returns only
the 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 Whitelisting
IP 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.md
index 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.md
index 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. Apply
retention/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?**