Skip to content

Document bridge API authentication #223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
+24 −1
Open

Document bridge API authentication #223

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion api-reference/bridge.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 |
Expand All @@ -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",
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 |