Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: warn that the bootstrap key file has no trailing newline

Yudhi Armyndharis9709e7679d86
diff --git a/README.md b/README.md
index 357e97148..b5efa9eff 100644
--- a/README.md
+++ b/README.md
@@ -190,7 +190,8 @@ docker compose -f docker-compose.dev.yml up -d
```
**Your API key.** The first boot generates an admin API key, prints it once in the log and stores it at
-`/app/data/.api-key` inside the container. Read it with `docker exec openwa-api cat /app/data/.api-key`,
+`/app/data/.api-key` inside the container. Read it with `docker exec openwa-api cat /app/data/.api-key`
+(the file has no trailing newline, so the shell prompt follows the key on the same line; copy only the key),
then use it to sign in to the dashboard and as the `X-API-Key` header wherever this README shows
`YOUR_API_KEY`. Later boots log only a masked prefix. See [API Key](docs/README.md#api-key).
diff --git a/charts/openwa/templates/NOTES.txt b/charts/openwa/templates/NOTES.txt
index 3d4e2ad44..7c627b419 100644
--- a/charts/openwa/templates/NOTES.txt
+++ b/charts/openwa/templates/NOTES.txt
@@ -8,7 +8,8 @@ OpenWA has been installed as release "{{ .Release.Name }}".
kubectl -n {{ .Release.Namespace }} rollout status statefulset/{{ include "openwa.fullname" . }}
2. Get the API key. If secretEnv.API_MASTER_KEY was left empty, the app generated
- one on first boot and stored it on the PVC:
+ one on first boot and stored it on the PVC (the file has no trailing newline, so copy only the key,
+ not the prompt after it):
kubectl -n {{ .Release.Namespace }} exec {{ include "openwa.fullname" . }}-0 -- cat {{ (.Values.env | default dict).BOOTSTRAP_KEY_FILE | default "/app/data/.api-key" }}
3. Reach the API + dashboard:
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index f0030509c..dc7380c82 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -112,7 +112,8 @@ found where it was saved, or replaced. Try these in order. If every key stopped
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`, with
`docker compose exec openwa-api cat /app/data/.api-key` on the compose deployment, or with
- `kubectl exec openwa-0 -- cat /app/data/.api-key` on the Helm chart (release `openwa`). The key
+ `kubectl exec openwa-0 -- cat /app/data/.api-key` on the Helm chart (release `openwa`). The file has no
+ trailing newline, so the shell prompt follows the key on the same line: copy only the key. The key
manages keys only while it still meets step 2's conditions. Once it is demoted from `admin`,
given any `allowedSessions` or `allowedChats`, or given `allowedIps` that exclude your address,
the file and the banner line remain but key management is refused; go on to step 2 or 3.
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 0855cad6e..2518897f5 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -1420,6 +1420,14 @@ retention/encryption to completed archives externally; see the [backup and resto
> A: Keys are stored hashed, so the database cannot give it back. Try the key in `data/.api-key` (or `BOOTSTRAP_KEY_FILE`), or the `API_MASTER_KEY` value set when the key table was last seeded, which still works while that key is an active, unscoped ADMIN key. Failing that, 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).
+**Q: The key from `data/.api-key` is refused with `Invalid API key`. What is wrong?**
+
+> A: A `401 Invalid API key` means the key's hash is not in the key table this instance reads. The usual
+> causes, in order: the pasted string is not the stored key (the file has no trailing newline, so a shell
+> prompt follows the key on the same line; copy only the key); another instance or database answers
+> than the one that generated it; or `API_KEY_PEPPER` was set or changed after the key was created, which
+> invalidates every key (see [Security](./04-security-design.md)).
+
### Webhook Questions
**Q: What events can I subscribe to?**