From 88ff722f94b7b829da8c9c6799b3255de406d4d7 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Tue, 28 Jul 2026 18:37:31 -0700 Subject: [PATCH] docs(api-server): document profile-bound HTTP auth from #72285 The multiplexed listener now rejects the default API_SERVER_KEY on /p// prefixes (fail-closed per-profile keys). Add the multi-profile routing section with an explicit breaking-change callout for the next release notes. --- .../docs/user-guide/features/api-server.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/website/docs/user-guide/features/api-server.md b/website/docs/user-guide/features/api-server.md index 8380d63131458..cfb87fcfd94c2 100644 --- a/website/docs/user-guide/features/api-server.md +++ b/website/docs/user-guide/features/api-server.md @@ -517,6 +517,27 @@ Authorization: Bearer *** Configure the key via `API_SERVER_KEY` env var. If you need a browser to call Hermes directly, also set `API_SERVER_CORS_ORIGINS` to an explicit allowlist. +### Multi-profile routing (`/p//…`) + +When [multi-profile gateway routing](/user-guide/multi-profile-gateways) is +enabled (`gateway.multiplex_profiles`), the shared listener serves every +profile through a `/p//` URL prefix — and **authentication is bound +to the routed profile**: + +- Requests to `/p//v1/...` must present that profile's own + `API_SERVER_KEY` (from `~/.hermes/profiles//.env`). The default + listener's key is rejected on named-profile prefixes. +- Unprefixed routes and `/p/default/...` keep using the default profile's key. +- A named profile with no `API_SERVER_KEY` of its own fails closed — its + prefix is unreachable until you set one. + +:::warning Breaking change (July 2026) +Before this fix, a valid default-profile key was accepted on any +`/p//` prefix. If you relied on one shared key across profile +prefixes, set a distinct `API_SERVER_KEY` in each profile's `.env` — reused +default keys on named prefixes now return `401`. +::: + :::warning Security The API server gives full access to hermes-agent's toolset, **including terminal commands**. `API_SERVER_KEY` is **required for every deployment**, including the default loopback bind on `127.0.0.1`. Keep `API_SERVER_CORS_ORIGINS` narrow to control browser access when you explicitly allow browser callers. :::