> ## Documentation Index
> Fetch the complete documentation index at: https://piyushvyas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Transport

> WebSocket configuration, message format, authentication, and security for BAP connections.

## WebSocket Configuration

| Setting              | Default               | Description                                     |
| -------------------- | --------------------- | ----------------------------------------------- |
| **Endpoint**         | `ws://localhost:9222` | WebSocket URL for the BAP server                |
| **Health check**     | `GET /health`         | Returns `{"status":"ok","version":"0.8.0"}`     |
| **Max message size** | 10 MB                 | Configurable via `BAP_MAX_MESSAGE_SIZE` env var |

## Message Format

All messages follow the JSON-RPC 2.0 specification.

### Request

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "page/navigate",
  "params": {
    "url": "https://example.com",
    "waitUntil": "domcontentloaded"
  },
  "id": 1
}
```

### Success Response

```json theme={null}
{
  "jsonrpc": "2.0",
  "result": {
    "url": "https://example.com",
    "title": "Example Domain"
  },
  "id": 1
}
```

### Error Response

```json theme={null}
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32012,
    "message": "Element not found",
    "data": {
      "retryable": true,
      "retryAfterMs": 500,
      "details": { "selector": { "type": "text", "value": "Submit" } },
      "recoveryHint": "Run observe() to refresh interactive elements, then retry with an updated selector"
    }
  },
  "id": 2
}
```

### Notification (Server to Client)

Notifications have no `id` field and expect no response:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "notifications/console",
  "params": {
    "pageId": "page-1",
    "type": "error",
    "text": "Uncaught TypeError: Cannot read property 'x' of null"
  }
}
```

## Authentication

BAP supports optional token-based authentication via two mechanisms:

<Tabs>
  <Tab title="Query Parameter">`ws://localhost:9222?token=your-secret-token`</Tab>
  <Tab title="Header">`X-BAP-Token: your-secret-token`</Tab>
</Tabs>

When a token is configured on the server, all connections must provide a valid token. Connections without a valid token are rejected immediately.

## Security Features

### Domain Allowlist

The server supports a domain allowlist that restricts which URLs can be navigated to:

```bash theme={null}
# MCP server with domain restriction
npx @browseragentprotocol/mcp --allowed-domains "example.com,api.example.com"
```

Attempting to navigate to a domain not in the allowlist returns a `DomainNotAllowed` error (code `-32041`).

### Scope-Based Authorization

BAP defines four authorization scopes that control what actions a client can perform:

| Scope          | Allowed Operations                                              |
| -------------- | --------------------------------------------------------------- |
| **readonly**   | Observations only (screenshot, accessibility, content, observe) |
| **standard**   | Read + navigation + safe actions (click, fill, type)            |
| **full**       | All operations including storage, cookies, file upload          |
| **privileged** | Full + eval, network interception, approval override            |

### Network Event Redaction

Server-pushed network events automatically redact sensitive headers:

* `authorization`, `cookie`, `set-cookie`
* `x-api-key`, `x-auth-token`, `x-csrf-token`
* `proxy-authorization`
* All `postData` is blanket-redacted

### URL Validation

All navigation methods (`page/navigate`, `page/create`, `storage/setState`) validate URLs before execution. `javascript:` protocol and cloud metadata endpoints are blocked.

## Connection Management

### Auto-Reconnect (Client SDK)

The TypeScript and Python SDKs implement exponential backoff reconnection:

```
Attempt 1: delay * 2^0 = 1000ms
Attempt 2: delay * 2^1 = 2000ms
Attempt 3: delay * 2^2 = 4000ms
...
Max attempts: 5 (configurable)
```

### Request Timeout

All requests have a 30-second default timeout. Timed-out requests receive a `Timeout` error (code `-32016`) with `retryable: true`.

### Concurrent Requests

The protocol supports multiple in-flight requests. Each request gets a unique numeric ID, and responses are matched by ID. There is no ordering guarantee between independent requests.