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

# Beacon Server

> Your traffic collection point in Esper — receives and processes events from your applications and infrastructure for real-time analysis and policy enforcement.

## How It Works

When you use Esper, your traffic data flows through the Beacon Server:

1. **Traffic Collection**: Your events are automatically forwarded to the Beacon Server
2. **Authentication**: Only traffic with valid API keys is accepted
3. **Processing**: Events are validated and prepared for analysis
4. **Policy Evaluation**: Events are evaluated against your deployed policies

## Sending Traffic to Beacon

### Automatic Collection (Recommended)

The easiest way to send traffic is using `esper capture`:

```bash theme={null}
# Start automatic traffic forwarding
esper capture run
```

This command:

* Monitors your network traffic automatically
* Forwards relevant events to the Beacon Server
* Requires zero changes to your applications
* Continues working even if Esper has issues (fail-safe design)

### Cloud HTTP

If the customer is using `cloud`, send the observed request or event to
Esper over HTTP and wait for the mitigation context in the response.

<Info>
  **Authentication**

  Cloud ingest uses the `x-esper-api-key` header. The customer only needs their
  Esper API key to start sending traffic.
</Info>

<Warning>
  **Integration Point Required**

  If the customer is not touching code, they still need some place to attach that
  header, such as middleware, a reverse proxy, a serverless platform hook, or a
  prebuilt Esper connector.
</Warning>

<Tip>
  **Start From A Shipped Integration**

  If you want a guided setup instead of building the request boundary yourself,
  start with the [Integrations](./integrations) section.
</Tip>

```bash theme={null}
curl -X POST https://api.esper.example/api/v1/beacon/event \
  -H "x-esper-api-key: YOUR_ESPER_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "tenant_id": "11111111-1111-1111-1111-111111111111",
    "source": "web",
    "observed_at": "2026-03-26T12:00:00Z",
    "idempotency_key": "req-0001",
    "request": {
      "method": "POST",
      "path": "/login",
      "client_ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0"
    },
    "fields": {
      "email": "user@example.com",
      "account_id": "acct-123"
    }
  }'
```

Minimal response shape:

```json theme={null}
{
  "item_id": "8bfc42be-8c1c-4c69-bc92-2d16d1f7d7e8",
  "lookup_entity_id": "1b1d1bb1-5ce1-59fd-bf3e-939e6d8f3d26",
  "active_mitigation": {
    "decision": "Block"
  }
}
```

<Tip>
  **For new customers, start with `cloud` before you introduce Hybrid. It is**

  the shortest path to a working integration.
</Tip>

### Direct API Integration

For custom integrations, send the same structured event shape directly to the
Beacon ingest API:

```bash theme={null}
curl -X POST https://api.esper.example/api/v1/beacon/event \
  -H "x-esper-api-key: YOUR_ESPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "11111111-1111-1111-1111-111111111111",
    "source": "api",
    "observed_at": "2026-03-26T12:00:00Z",
    "fields": {
      "action": "login",
      "user": "user@example.com"
    }
  }'
```

## Security

* **Encrypted Transport**: All traffic uses TLS encryption
* **API Key Authentication**: Each request must include your unique API key
* **Rate Limiting**: Automatic protection against traffic spikes
* **Data Isolation**: Your events are completely isolated from other customers

## Performance

The Beacon Server is designed to handle high-volume traffic:

* Automatically scales during traffic spikes
* Batching support for improved efficiency
* Geographic distribution for low latency

## Monitoring

You can monitor your Beacon Server usage in the Esper dashboard:

* Events received per second
* Authentication failures
* Processing latency
* Error rates

## Integration guides

Use the recipe-backed docs when you want Esper at an existing traffic boundary:

* [Vercel](./integrations/vercel)
* [Cloudflare Workers](./integrations/cloudflare)
* [AWS Lambda](./integrations/aws)
* [Heroku](./integrations/heroku)