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.

Esper integrations collect request context at an application or edge boundary, send it to the runtime decision API, and apply the returned action at that boundary. Use these guides when you want Esper to sit at a boundary you already control, such as:
  • Vercel
  • Cloudflare Workers
  • AWS Lambda
  • Google Cloud Functions
  • Heroku
Recipes Back These GuidesEach integration page is based on the recipe source shipped in this repository under recipes/. The docs explain what to configure, what the recipe is doing, and where it fits in the broader Esper workflow.

​
What every integration must send

Customers should not need to guess what Esper needs. At a minimum, every integration should preserve the original request context well enough for Esper to evaluate policy and return one immediate action consistently.
Primary Runtime ContractFor cloud, the integration should call POST /api/v1/runtime/mitigation with:
  • x-esper-api-key
  • request context
  • observed timestamp
  • optional return URL for challenge handoff
  • any request fields your policy depends on
The request context you preserve should include:
  • client IP
  • user agent
  • method
  • path
  • query params
  • request headers
  • cookies when relevant
Keep The Cloud Contract SmallCloud integrations should keep the logical runtime decision contract the same regardless of transport or provider details. The customer should still only need an API key and an integration boundary that can preserve request context.
Preserve Original Request ContextIf your integration drops IP, user agent, path, or headers before forwarding to Esper, entity mapping and policy evaluation will drift from the real request. The safest pattern is to forward the original request context as completely as your platform allows.

​
Which Esper headers matter

Different runtime paths need different Esper-owned identifiers. The goal is to keep customer-facing contracts small and stable.
FlowWhat customer sendsWhy it matters
Runtime decisionx-esper-api-keyAuthenticates the synchronous /api/v1/runtime/mitigation request
Managed challenge follow-upX-Esper-Decision-IDUsed only when a lower-level challenge flow is started outside the runtime wrapper
Local mitigation enforcementX-Esper-Hybrid-KeyLets local enforcement identify the active mitigation record without exposing internal Esper ids
Customer Integrations Should Prefer /api/v1/runtime/mitigationThe customer-facing integration should not make separate manual Beacon, mitigation, and challenge-orchestration calls. Esper should receive one runtime request and return one immediate action: allow, challenge, or block.

​
What to preserve from the original request

Regardless of platform, the integration should preserve these fields whenever they are available:
  • client IP, including trusted forwarded IP headers from your platform
  • user agent
  • request method
  • request path
  • query string parameters
  • relevant request headers
  • cookies if your rules or entity model depend on them
Challenge Redirect DataFor managed challenge flows, redirect data belongs in the challenge start query string, not in a JSON body. Use query parameters such as return_url, path, query_params[...], and route_params[...].

​
How to choose an integration

  • Choose Vercel if your application already runs on Vercel and you want a simple serverless entry point.
  • Choose Cloudflare Workers if you want a low-overhead edge wrapper that verifies managed challenge returns, asks Esper for one runtime decision, and applies allow, challenge, or block before origin.
  • Choose AWS Lambda if your traffic enters through API Gateway and Lambda.
  • Choose Google Cloud Functions if your traffic enters through an HTTP Cloud Function or Cloud Run function.
  • Choose Heroku if you want a simple app-process proxy with minimal infrastructure work.

​
What each integration does

At a high level, each recipe:
  1. receives the incoming request
  2. gathers request context such as IP, path, method, user agent, headers, and query params
  3. asks Esper for a mitigation decision
  4. applies the result at that boundary
  5. forwards traffic or telemetry as needed
Start With The Simplest Enforcement StoryIf you are onboarding a new property, validate allow first, then introduce challenge, and only later rely on automatic block. Monitoring remains internal to Esper and should not require a separate customer-facing action mode.

​
Integration checklist by mode

​
Runtime decision

  • Send x-esper-api-key
  • Call POST /api/v1/runtime/mitigation
  • Preserve original request context in the request body
  • Make sure client IP and user agent survive platform forwarding

​
Managed Esper challenge

  • Let the integration consume Esper’s challenge action directly
  • Use the returned redirect_url immediately
  • Treat separate challenge-start calls as lower-level plumbing, not the primary customer flow

​
Local mitigation enforcement

  • Preserve or inject X-Esper-Hybrid-Key where your local enforcement path requires it today
  • Keep the same entity mapping inputs stable between ingest and enforcement
  • Do not invent a second actor identity model at the edge

​
Generic monitor / block / challenge handling

  • Forward enough request context for Esper to make the right decision
  • Apply only the returned action:
    • allow
    • challenge
    • block
  • Keep policy evaluation and mitigation handling at the same traffic boundary when possible

​
What to expect from the recipes today

  • They are practical starting points for adapting the recipe code.
  • They keep setup code small enough to review and adapt.
  • They make the request boundary explicit, which is the key place where Esper receives context and returns a decision.

​
Integration guides