test

doc/lwc-doc/docs/getting-started/control/rest-api.en.md

@@ -16,6 +16,7 @@ web:
   enabled: true
   host: 0.0.0.0
   port: 8007
+  token: "replace-with-a-long-secret-token"
   endpoints: pkg://iiwa_config/config/api_endpoints.yaml
   joint_limits: pkg://iiwa_config/config/moveit/joint_limits.yaml
 ~~~
@@ -28,7 +29,65 @@ After starting the stack with **cobot run**, the server is available at **http:/
 
 There is no separate health-check endpoint. If Swagger UI opens, the HTTP server is running. Readiness of ROS components is checked when a specific endpoint is called.
 
-By default, the server listens on all network interfaces and does not use authentication. Do not expose port 8007 to an untrusted network. For local access, set **host: 127.0.0.1**. For remote access, restrict the network with firewall rules or a VPN.
+When `host` is not `localhost`, `127.0.0.1`, or another loopback address, the
+`token` field is required; otherwise the server exits during startup. When
+`token` is set, Bearer authentication applies to every REST route and to the
+MCP route `/mcp/mcp`, including with a local `host`.
+
+The `/docs`, `/redoc`, and `/openapi.json` resources are available without a
+header so the browser can load Swagger UI. This does not expose control
+commands. Open `/docs`, click **Authorize**, paste the `web.token` value without
+the word `Bearer`, and confirm. Swagger adds the header to API requests.
+
+The token is stored in **cobot-setting.yaml**. Do not add it to documentation,
+scripts, or public repositories. If it is exposed, replace it and restart the
+stack. For remote access, also restrict port 8007 with a firewall or VPN.
+
+### REST and MCP authentication
+
+Every request to a protected REST route or MCP must include the following header
+when `web.token` is set:
+
+~~~ http
+Authorization: Bearer <web.token value>
+~~~
+
+Client setup examples:
+
+=== "curl"
+
+    ~~~ bash
+    HOST=http://localhost:8007
+    API_TOKEN='copy web.token from cobot-setting.yaml'
+    AUTH_HEADER="Authorization: Bearer ${API_TOKEN}"
+    curl -sS -H "${AUTH_HEADER}" $HOST/robot/joint_states
+    ~~~
+
+=== "Python"
+
+    ~~~ python
+    import httpx
+
+    HOST = "http://localhost:8007"
+    API_TOKEN = "copy web.token from cobot-setting.yaml"
+    HEADERS = {"Authorization": f"Bearer {API_TOKEN}"}
+    response = httpx.get(f"{HOST}/robot/joint_states", headers=HEADERS, timeout=10)
+    response.raise_for_status()
+    ~~~
+
+=== "MATLAB"
+
+    ~~~ matlab
+    HOST = 'http://localhost:8007';
+    API_TOKEN = 'copy web.token from cobot-setting.yaml';
+    readOpts = weboptions('Timeout', 10, ...
+        'HeaderFields', {'Authorization', ['Bearer ' API_TOKEN]});
+    jointState = webread([HOST '/robot/joint_states'], readOpts);
+    ~~~
+
+Pass the same header when connecting an MCP client to
+`http://<host>:8007/mcp/mcp`. If the client supports custom HTTP headers, set
+`Authorization: Bearer <web.token value>` in its connection settings.
 
 ## Preparing the examples
 
@@ -648,4 +707,4 @@ When troubleshooting, proceed from simple checks to more complex ones:
 3. Make sure that the complete stack is running: `controller_manager`, MoveIt, and `iiwa_motion_server`.
 4. After starting a sequence, inspect **/sequences/logs**. After publishing a trajectory, inspect **/trajectory/logs**.
 
-The MCP server runs in the same process but provides a separate interface at **http://server-address:8007/mcp/mcp**. For ordinary HTTP integrations, use the endpoints documented on this page.
+The MCP server runs in the same process but provides a separate interface at **http://server-address:8007/mcp/mcp**. It uses the same Bearer token; pass the `Authorization` header when connecting an MCP client. For ordinary HTTP integrations, use the endpoints documented on this page.