Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(security): describe API_MASTER_KEY as a first-boot seed
Yudhi Armyndharisf4a59766ca1a
diff --git a/.env.example b/.env.exampleindex 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.mdindex 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.```mermaidflowchart TBdiff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.mdindex 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 hashesAPI_KEY_PEPPER=optional-key-hashing-pepper