From 8c7f815650287160a56fd1a1d9fb34819dd3b051 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Sun, 29 Mar 2026 21:51:55 +0000
Subject: [PATCH] Document bridge API authentication via x-bridge-secret header

Generated-By: mintlify-agent
---
 api-reference/bridge.mdx | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/api-reference/bridge.mdx b/api-reference/bridge.mdx
index 8ff04d8..07ef6a3 100644
--- a/api-reference/bridge.mdx
+++ b/api-reference/bridge.mdx
@@ -7,6 +7,24 @@ description: "Internal message bus for agent coordination across channels"
 
 Send and receive messages through the agent bridge, a private message bus used for coordination between agents and operators. Messages are organized by channel and include unread tracking per reader.
 
+## Authentication
+
+All bridge endpoints require the `x-bridge-secret` header when the `BRIDGE_SECRET` environment variable is configured. When `BRIDGE_SECRET` is not set, authentication is disabled (development mode only).
+
+| Header | Type | Required | Description |
+|--------|------|----------|-------------|
+| `x-bridge-secret` | string | Yes (when `BRIDGE_SECRET` is set) | Shared secret for authenticating bridge requests. Must match the server-side `BRIDGE_SECRET` value. |
+
+Unauthenticated requests return a `401` response:
+
+```json
+{
+  "error": "unauthorized"
+}
+```
+
+<Warning>In production, always set the `BRIDGE_SECRET` environment variable to secure the bridge endpoints. Without it, any caller can send and read bridge messages.</Warning>
+
 ## Send a message
 
 ```http
@@ -52,6 +70,7 @@ Sends a message to a bridge channel.
 
 | Code | Description |
 |------|-------------|
+| 401 | `unauthorized` — missing or invalid `x-bridge-secret` header |
 | 400 | `sender and content are required` — the `sender` or `content` field is missing from the request body |
 | 400 | `invalid sender` — the `sender` value is not one of the allowed identities |
 | 500 | Failed to send message |
@@ -61,6 +80,7 @@ Sends a message to a bridge channel.
 ```bash
 curl -X POST /api/bridge/send \
   -H "Content-Type: application/json" \
+  -H "x-bridge-secret: your-bridge-secret" \
   -d '{
     "sender": "atlas-main",
     "channel": "tasks",
@@ -130,12 +150,14 @@ Retrieves unread messages from a bridge channel. Messages are automatically mark
 
 | Code | Description |
 |------|-------------|
+| 401 | `unauthorized` — missing or invalid `x-bridge-secret` header |
 | 500 | Failed to fetch messages |
 
 ### Example
 
 ```bash
-curl "/api/bridge/inbox?channel=tasks&reader=atlas-main&limit=10"
+curl -H "x-bridge-secret: your-bridge-secret" \
+  "/api/bridge/inbox?channel=tasks&reader=atlas-main&limit=10"
 ```
 
 ## Bridge health
@@ -187,4 +209,5 @@ Returns the current status of the bridge message bus, including total message co
 | Code | Description |
 |------|-------------|
 | 200 | Bridge health check succeeded |
+| 401 | `unauthorized` — missing or invalid `x-bridge-secret` header |
 | 500 | Database is unreachable |