Skip to main content

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.

By the end of this guide, you’ll have a working policy that can allow, challenge, or block requests from request context, actions, entities, and mitigation settings.

​
What you are trying to accomplish

By the end of this setup, you should have:
  • One tenant selected.
  • One API key for an ingest source.
  • One action definition.
  • One entity definition.
  • One mitigation.
  • One deployed policy.
  • One integration path connected to your traffic boundary.
  • Enough traffic to see policy-attributed results.

​
0. Pick an operation mode

Before setup, decide whether this tenant will use:
  • cloud: HTTP requests directly to Esper through an integration
  • hybrid: customer-managed Esper Hybrid runtime and local sync
See Operation Modes for the deployment tradeoffs.

​
1. Authorization

The current hosted login flow supports: 
/auth/github/login
/auth/google/login
See Authorization for complete authentication details.

​
2. Choose an integration boundary

Before you send live traffic, decide where Esper will plug into your stack. Common starting points:
  • Vercel
  • Cloudflare Workers
  • AWS Lambda
  • Heroku
See Integrations for the current recipe-backed setup guides.

​
3. Create or select a tenant

Use Tenants to:
  • Create a tenant with name and slug.
  • Switch the active tenant.
  • Manage memberships for that tenant.
Most of the rest of the console is tenant-scoped, so this is the first required step after authentication.

​
4. Issue an API key

Use API Keys to create a credential for ingest. Create a key with:
  • name: The label your team sees in the console.
  • trust_level: The trust classification for requests signed by this key.
  • secret: The shared secret the sending system uses to authenticate.
Use one key per major sending system. Good first examples:
  • Example: Web app production
  • Example: Checkout API
  • Example: Partner gateway

​
5. Define an action

Use Policies → Actions to define a property-specific semantic behavior. Examples:
  • Example: login
  • Example: view_article
  • Example: checkout_complete
An action is evaluated from traffic expressions over automatically encoded fields. The point is to label behavior in tenant language, not backend language.

​
6. Define an entity

Use Policies → Entities to define how Esper should identify and group traffic. New tenants already start with bundled system entity definitions, so you can either use those immediately or create a tenant-specific definition here. Examples:
  • Example: client_ip + user_agent
  • Example: ip + referer
  • Example: cookie + payload traits
Esper still performs encoding automatically. The entity definition is where the tenant says which signals should count as identity.

​
7. Define mitigation

Use Policies → Mitigation to create reusable response behavior. Current modes:
  • Monitor: Observe matching traffic without taking an active step.
  • Challenge: Ask the client to complete an additional verification step.
  • Block: Stop the matching request from continuing.
Start with Monitor until you trust the traffic pattern and the policy shape.

​
8. Compose a policy

Use Policies → Policies to bind everything together. A policy can include:
  • expression: The shared traffic condition that decides when the policy is in play.
  • clauses: One or more policy clauses that each bind a clause match condition, actions, entities, mitigations, and an optional window.
  • enabled: Whether the policy is active.
Each clause can independently say, for example, “when the foo=bar query parameter is present, apply this mitigation” or “for this entity, if it exceeds this share of tenant traffic over this window, apply this mitigation.” This is the final composed object the backend evaluates. If you want Esper to react to repeated traffic instead of a single request, add a clause window here. Current defaults are:
  • 1 minute
  • 3 minutes
  • 5 minutes
  • 60 minutes
This window feature is configured on policy clauses. Clause windows can be:
  • absolute count thresholds such as “5 requests in 1 minute”
  • traffic-share thresholds such as “more than 20% of tenant traffic in 1 hour”

​
9. Connect traffic and validate results

Deploy the integration you chose earlier, then send traffic through it.
Recommended RolloutStart by deploying the policy in Monitor. Once the integration is stable and the results look correct, move to Challenge. Treat Block as the last step in the rollout.
Once traffic is flowing for the active tenant, use:
  • Results to inspect policy performance.
  • Audit to review administrative changes.
What success looks like:
  • Traffic arrives through the configured source.
  • The deployed policy begins accumulating attributed decisions.
  • Results show observe, challenge, or block counts by policy.
Next: Overview