Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(security): describe API_MASTER_KEY as a first-boot seed

Yudhi Armyndharisf4a59766ca1a
diff --git a/.env.example b/.env.example
index 419dbcf75..3418bbb3a 100644
--- a/.env.example
+++ b/.env.example
@@ -804,7 +804,9 @@ PLUGINS_DIR=./data/plugins # Plugin directory (default: ./data/plugins)
# =============================================================================
# SECURITY
# =============================================================================
-# Master API key (leave empty to disable, or set to secure value). In production the
+# First-boot seed for the initial ADMIN key, read only when no API key exists yet. Leave it
+# empty to generate a random key (data/.api-key). Changing it later has no effect: rotate by
+# minting a new ADMIN key via POST /api/auth/api-keys and revoking the old one. In production the
# boot refuses a value shorter than 32 characters or one that is a known default.
# API_MASTER_KEY=
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index 73380752a..0d4b76dc0 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -539,11 +539,13 @@ flowchart TB
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| Database credentials | Environment variable | 90 days |
| Redis password | Environment variable | 90 days |
-| API master key (`API_MASTER_KEY`) | Environment variable | 180 days |
+| API master key (`API_MASTER_KEY`) | Environment variable (first-boot seed only) | Not via the env var; see the note below |
| API key pepper (`API_KEY_PEPPER`) | Environment variable | Rotating it invalidates all existing key hashes |
| Webhook secrets | Database — **plaintext**; not in the webhook read DTOs, and omitted from `GET /api/infra/export-data` webhook rows | Per webhook |
| Session auth state | File system (data volume) — **not encrypted** | Never (tied to the WA session) |
+> `API_MASTER_KEY` only seeds the first ADMIN key, and is read only while the key table is empty. Changing it later has no effect: the new value never authenticates and the seeded key stays valid. Rotate by minting a new ADMIN key with `POST /api/auth/api-keys` and revoking the seeded `Default Admin Key`.
+
> There is no application `ENCRYPTION_KEY` — OpenWA does not encrypt data at rest (see §4.4). The rotation cadences above are operational recommendations, not enforced by the app.
### Environment Variables Security
@@ -612,7 +614,7 @@ const masterKey = getSecret('API_MASTER_KEY');
### Key Rotation Procedure
-> **Not applicable today.** OpenWA stores no encrypted-at-rest data (see §4.4), so there is no data-encryption key to rotate and no `rotateEncryptionKey()` in the codebase. The flow below is illustrative for if/when field-level encryption is added. To rotate the `API_MASTER_KEY` or `API_KEY_PEPPER`, use the API-key endpoints (§4.2) — rotating the pepper invalidates existing key hashes.
+> **Not applicable today.** OpenWA stores no encrypted-at-rest data (see §4.4), so there is no data-encryption key to rotate and no `rotateEncryptionKey()` in the codebase. The flow below is illustrative for if/when field-level encryption is added. To rotate the key seeded from `API_MASTER_KEY`, mint a new ADMIN key through the API-key endpoints (§4.2) and revoke the seeded one; editing the env var has no effect after first boot. Rotating `API_KEY_PEPPER` invalidates every existing key hash.
```mermaid
flowchart TB
diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.md
index 1e76d610b..dcdc5d052 100644
--- a/docs/10-devops-infrastructure.md
+++ b/docs/10-devops-infrastructure.md
@@ -475,8 +475,9 @@ PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox
# ===========================================
# SECURITY
# ===========================================
-# Generate with: openssl rand -base64 32
-API_MASTER_KEY=your-master-api-key
+# First-boot seed for the initial ADMIN key, ignored once any key exists. Leave it unset to
+# generate a random key into data/.api-key, or set one generated with: openssl rand -base64 32
+# API_MASTER_KEY=
# Optional HMAC pepper so a DB leak alone can't precompute key hashes
API_KEY_PEPPER=optional-key-hashing-pepper