> ## 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.

# Entities

> Entities define how Esper groups related requests for policy evaluation.

Esper encodes traffic automatically, but the tenant still needs to define what
counts as an entity for their property.

New tenants are bootstrapped with bundled system entity definitions so the
workspace is immediately usable before you author your own custom identity
rules.

If you are unsure which fields you can use, open the
[Field Reference](./field-reference). It explains the field list shown in the
builder in non-technical language.

Examples:

* Example: `client_ip + request_header_user_agent`
* Example: `cookie + path pattern`
* Example: `ip + referer + action`

## System starter entities

Esper currently seeds new tenants with these system-defined entity definitions:

* `ip-user-agent`: `client_ip + user_agent`
* `bot-crawlers`: `user_agent` when the request matches known crawler tokens from OpenAI, Anthropic, Google, Apple, Meta, and Cloudflare

These starter definitions are bundled with the product itself and loaded from a
versioned asset, so the backend and CLI use the same default entity shapes.

## What you define for an entity

When creating an entity definition, you usually choose:

* `name`: A clear label for the identity rule.
* `description`: Optional context about what the entity represents.
* `key_fields`: The fields Esper should combine to identify the same actor,
  device, account, or session across requests.
* `match_expression`: An optional condition that limits when this entity
  definition applies.

## Why this matters

Entity definitions tell Esper how to:

* Group related traffic.
* Accumulate state.
* Analyze repeated behavior.
* Bind policies to the right identity semantics.

## Choosing key fields

Key fields tell Esper which values should stay stable when two requests belong
to the same real-world actor, device, session, or account.

In the builder, you are usually choosing from the tenant's available field
catalog directly. For match expressions, you may also use request-oriented
conditions such as method, header, query parameter, cookie, or body data
reference.

Examples of strong key fields:

* Account or customer identifiers.
* Stable device identifiers.
* Source identifier plus browser identity.
* Client IP plus user agent when you need a practical edge-oriented fallback.
* Well-defined session fields.

Examples of weak key fields:

* Request timestamps.
* Values that are often blank.
* Values that change on every request.
* Fields that are too broad on their own, such as only the request path.

## Where the field list comes from

The field list in the Entities builder is tenant-specific. Esper shows the
fields currently available for this tenant, including:

* Captured fields.
* Derived fields.
* Action fields.

If a field you expect is missing, contact your Esper administrator or
support team.