Quickstart

This quickstart follows the current app flow from sign-in to a first working tenant configuration.

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 encoding version that extracts useful fields
• one rule that produces a visible decision
• enough traffic or replay history to confirm the system is working

1. Sign in

The login screen sends operators to the backend endpoint:

/auth/github/login

After the GitHub flow completes, the console expects a token in the URL hash on /login/callback and stores it in browser local storage as esper.auth_token.

Why this matters:

• this token is what keeps you signed into the console
• if sign-in fails, most pages will redirect back to /login

2. Create or select a tenant

Use the Tenants page to:

• create a tenant with name and slug
• switch the active tenant
• edit tenant metadata
• manage memberships for the selected tenant

Most of the rest of the console is tenant-scoped, so this is the first required step after authentication.

Plain English:

• a tenant is one workspace
• each workspace has its own keys, rules, encoding versions, events, and decisions
• when you switch tenants, the rest of the console updates to that workspace

3. Issue an API key

Use API Keys to create a source-bound credential. The current form requires:

• name
• source_id
• trust_level
• secret

Supported trust levels are:

• External
• Internal
• Trusted

What these mean:

Field	Meaning	Why it matters
name	Human-friendly label for the key	Helps operators recognize the source later
source_id	Stable identifier for the sending system	Appears throughout the console on events and state
trust_level	How trusted this source should be treated	Useful metadata for source classification
secret	The shared credential used by the source	Required for the backend to authenticate ingest

Safe first setup:

• use a simple name like Web app production
• use a stable source_id like web-prod
• start with External unless you already have a stronger trust model

4. Create an encoding version

Use Encoding to create a numbered encoding version. The current form lets you set:

• version number
• version status
• summary
• runtime policy
• extracted fields
• derived fields
• actions

Without an encoding plan, the backend has no tenant-owned extraction contract to apply.

Plain English:

• the encoding plan tells Esper how to read an incoming request
• it turns raw request data into consistent fields that rules can use
• if rules are your policy, encoding is the translation layer underneath it

Good first goal:

• extract one identity field such as email
• define one action such as login_attempt
• keep the default decision as Observe until you trust the results

5. Create a rule

Use Rules to create a rule with:

• name
• description
• priority
• outcome
• expression as JSON

Supported outcomes are:

• Allow
• Observe
• Challenge
• Block

Plain English:

• a rule says "if these conditions are true, return this outcome"
• Observe is the safest starting outcome because it records behavior without blocking anything
• Block is appropriate only after you understand the data and have replayed or reviewed enough traffic

6. Validate behavior

Once traffic is flowing for the active tenant, use:

• Events to inspect persisted event history
• Decisions to inspect evaluated outcomes
• Entities and Sessions to inspect live state snapshots
• Jobs to launch replay work against a historical time range
• Audit to review admin-side mutations

What success looks like:

• Events show incoming traffic
• Decisions show at least one evaluated outcome
• Entities or Sessions show saved state for the traffic you sent
• Jobs can replay historical windows without errors

Next: Console overview