---
title: "Auth"
description: "Authenticate mid-session to receive user-specific events. Send your JWT token (same as REST API) to upgrade from app-level to user-level auth. Supports re-authentication for token refresh or user switch. Connect-time auth: Pass ?token=eyJ... as a query param alongside appId."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

## Connection

```
wss://ws.agg.market/ws
```

Production WebSocket server.

**Connection:** `wss://ws.agg.market/ws?appId=xxx` (required). Optionally pass `&token=eyJ...` for user-level auth on connect.

**Reconnection:** Reconnect with exponential backoff + jitter: `delay = min(1s × 2^attempt + random(0–1s), 30s)`. On reconnect, re-subscribe to all channels.

**Heartbeat:** The service emits a JSON `heartbeat` message clients can observe directly.

### Security schemes

<ParamField body="appId" type="userPassword">
  App-level auth: pass appId as a query parameter on connect. Required for all connections. The appId must belong to an active app with matching allowed origins.
</ParamField>
<ParamField body="jwt" type="JWT">
  User-level auth: pass JWT as token query param on connect, or send &#123; action: 'authenticate', token &#125; mid-session. Required for user-specific events (orders, balances). Same JWT as the REST API.
</ParamField>

## Send

### Authenticate user mid-session

Upgrade connection to user-level auth. Uses the same JWT as the REST API. Supports re-authentication for token refresh or user switch.

<ParamField body="action" type={"\"authenticate\""} required />
<ParamField body="token" type="string" required>
  JWT token for user-level auth (same token used for REST API)
</ParamField>

```json
{
  "action": "authenticate",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

## Receive

### User authenticated

Confirms successful mid-session authentication

<ParamField body="type" type={"\"authenticated\""} required />
<ParamField body="userId" type="string" required />

```json
{
  "type": "authenticated",
  "userId": "usr_xyz789"
}
```

### Connection acknowledged

Sent immediately after successful connection. Includes userId if JWT was provided on connect.

<ParamField body="type" type={"\"connected\""} required />
<ParamField body="appId" type="string" required />
<ParamField body="userId" type="string" />

```json
{
  "type": "connected",
  "appId": "app_demo123",
  "userId": "usr_xyz789"
}
```

### Heartbeat

Application-level heartbeat event for connection liveness

<ParamField body="type" type={"\"heartbeat\""} required />
<ParamField body="ts" type="number" required>
  Server timestamp in milliseconds
</ParamField>

```json
{
  "type": "heartbeat",
  "ts": 1710000000000
}
```

### Error

Sent on validation failures, auth errors, or malformed messages

<ParamField body="type" type={"\"error\""} required />
<ParamField body="message" type="string" required />

```json
{
  "type": "error",
  "message": "Invalid request: outcomeIds must be a non-empty array"
}
```