Skip to main content

Quickstart

This quickstart walks through the fastest path from authorization to seeing your first working policy.

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.
  • Enough traffic to see policy-attributed results.

For self-hosted or brokered local deployments, that also means having the runtime services running:

  • esper-server
  • esper-ingestion-broker
  • esper-mitigation-broker
  • esper worker run engine

1. Authorization​

The current hosted login flow supports:

/auth/github/login
/auth/google/login

See Authorization for complete authentication details.

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

3. Issue an API key​

Use API Keys to create a source-bound credential for ingest.

Create a key with:

  • name: The label your team sees in the console.
  • source_id: The identifier Esper stores with traffic from this source.
  • 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

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

5. Define an entity​

Use Policies → Entities to define how Esper should identify and group traffic.

Examples:

  • Example: source_id + request_header_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.

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

7. Compose a policy​

Use Policies → Policies to bind everything together.

A policy can include:

  • expression: The traffic condition that decides when the policy matches.
  • action_ids: The action definitions that must also match.
  • entity_definition_id: The optional entity definition used to group traffic.
  • mitigation_id: The mitigation Esper applies when the policy matches.
  • window: The optional monitoring window for repeated behavior checks.
  • enabled: Whether the policy is active.

This is the final composed object the backend evaluates.

8. Validate results​

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 ingestion broker accepts and stores incoming analysis work.
  • The engine worker claims that work and evaluates the deployed policy.
  • The mitigation broker stores the resulting mitigation decision.
  • The policy begins accumulating attributed decisions.
  • Results show observe, challenge, or block counts by policy.

Next: Console overview