From a6d5e4f3b528bd63bc24ffec0e33ebcb4cc2d5c1 Mon Sep 17 00:00:00 2001
From: Xubin Ren <52506698+Re-bin@users.noreply.github.com>
Date: Wed, 1 Jul 2026 13:07:36 +0800
Subject: [PATCH] docs(api): document wildcard bind authentication

---
 docs/openai-api.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/openai-api.md b/docs/openai-api.md
index 0307258a..6dbfc146 100644
--- a/docs/openai-api.md
+++ b/docs/openai-api.md
@@ -12,6 +12,32 @@ Run the CLI check first. If `nanobot agent -m "Hello!"` fails, fix provider or c
 
 For setup help, see [`quick-start.md`](./quick-start.md), [`providers.md`](./providers.md), and [`troubleshooting.md`](./troubleshooting.md).
 
+## Authentication
+
+Local-only `127.0.0.1` usage does not require an API key. If you bind the API
+server to all interfaces with `api.host: "0.0.0.0"` or `"::"`, nanobot requires
+`api.apiKey`; otherwise startup fails to avoid exposing an unauthenticated agent
+endpoint on the network.
+
+```json
+{
+  "api": {
+    "host": "0.0.0.0",
+    "port": 8900,
+    "apiKey": "${NANOBOT_API_KEY}"
+  }
+}
+```
+
+When `api.apiKey` is set, send it as a Bearer token on API routes. The health
+endpoint remains unauthenticated so local probes and load balancers can still
+check process health.
+
+```bash
+curl http://127.0.0.1:8900/v1/models \
+  -H "Authorization: Bearer $NANOBOT_API_KEY"
+```
+
 ## Behavior
 
 - Session isolation: pass `"session_id"` in the request body to isolate conversations; omit for a shared default session (`api:default`)