From 6cff644dc966639d437ac0f1d110f0b5f7261b6b Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 13:56:01 +0100 Subject: [PATCH] docs: refresh http endpoint auth refs --- docs/gateway/openai-http-api.md | 15 +++++++++++++-- docs/gateway/openresponses-http-api.md | 5 ++++- docs/gateway/tools-invoke-http-api.md | 15 +++++++++++++-- 3 files changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/gateway/openai-http-api.md b/docs/gateway/openai-http-api.md index b04bac9fb1d..5f81ab513a2 100644 --- a/docs/gateway/openai-http-api.md +++ b/docs/gateway/openai-http-api.md @@ -25,14 +25,25 @@ Under the hood, requests are executed as a normal Gateway agent run (same codepa ## Authentication -Uses the Gateway auth configuration. Send a bearer token: +Uses the Gateway auth configuration. -- `Authorization: Bearer ` +Common HTTP auth paths: + +- shared-secret auth (`gateway.auth.mode="token"` or `"password"`): + `Authorization: Bearer ` +- trusted identity-bearing HTTP auth (`gateway.auth.mode="trusted-proxy"`): + route through the configured identity-aware proxy and let it inject the + required identity headers +- private-ingress open auth (`gateway.auth.mode="none"`): + no auth header required Notes: - When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`). - When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`). +- When `gateway.auth.mode="trusted-proxy"`, the HTTP request must come from a + configured non-loopback trusted proxy source; same-host loopback proxies do + not satisfy this mode. - If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`. ## Security boundary (important) diff --git a/docs/gateway/openresponses-http-api.md b/docs/gateway/openresponses-http-api.md index 1876b415d95..4b7c181a1fc 100644 --- a/docs/gateway/openresponses-http-api.md +++ b/docs/gateway/openresponses-http-api.md @@ -22,7 +22,10 @@ Under the hood, requests are executed as a normal Gateway agent run (same codepa Operational behavior matches [OpenAI Chat Completions](/gateway/openai-http-api): -- use `Authorization: Bearer ` with the normal Gateway auth config +- use the matching Gateway HTTP auth path: + - shared-secret auth (`gateway.auth.mode="token"` or `"password"`): `Authorization: Bearer ` + - trusted-proxy auth (`gateway.auth.mode="trusted-proxy"`): identity-aware proxy headers from a configured non-loopback trusted proxy source + - private-ingress open auth (`gateway.auth.mode="none"`): no auth header - treat the endpoint as full operator access for the gateway instance - for shared-secret auth modes (`token` and `password`), ignore narrower bearer-declared `x-openclaw-scopes` values and restore the normal full operator defaults - for trusted identity-bearing HTTP modes (for example trusted proxy auth or `gateway.auth.mode="none"`), honor `x-openclaw-scopes` when present and otherwise fall back to the normal operator default scope set diff --git a/docs/gateway/tools-invoke-http-api.md b/docs/gateway/tools-invoke-http-api.md index 0d4b7cd99a7..fa57665b452 100644 --- a/docs/gateway/tools-invoke-http-api.md +++ b/docs/gateway/tools-invoke-http-api.md @@ -17,14 +17,25 @@ Default max payload size is 2 MB. ## Authentication -Uses the Gateway auth configuration. Send a bearer token: +Uses the Gateway auth configuration. -- `Authorization: Bearer ` +Common HTTP auth paths: + +- shared-secret auth (`gateway.auth.mode="token"` or `"password"`): + `Authorization: Bearer ` +- trusted identity-bearing HTTP auth (`gateway.auth.mode="trusted-proxy"`): + route through the configured identity-aware proxy and let it inject the + required identity headers +- private-ingress open auth (`gateway.auth.mode="none"`): + no auth header required Notes: - When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`). - When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`). +- When `gateway.auth.mode="trusted-proxy"`, the HTTP request must come from a + configured non-loopback trusted proxy source; same-host loopback proxies do + not satisfy this mode. - If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`. ## Security boundary (important)