API keys and ingest

The API key surface ties ingest clients to a tenant and a source_id.

What this page is for

Use this page when a system needs permission to send events into Esper.

Typical examples:

• your web application
• your backend API
• a partner integration
• an internal service emitting risk or fraud events

What an API key contains

The current model for an API key includes:

• api_key_id
• tenant_id
• name
• source_id
• trust_level
• created_at

When creating a key, the console collects:

• name
• source_id
• trust_level
• secret

What each field means

Field	Plain-English meaning	Why you care
api_key_id	The system-generated ID of the key record	Useful for support, auditing, and distinguishing similar keys
tenant_id	The workspace this key belongs to	Prevents environments from mixing together
name	A readable label for operators	Makes the key easy to recognize in the UI
source_id	The name of the sending system	Shows up later on events and some state views
trust_level	The trust classification for that source	Helps describe how the source should be treated
created_at	When the key record was created	Useful when tracing rollout history
secret	The shared credential used by the sending system	Required for authentication

Trust levels

Supported trust levels in the current UI and model:

• External
• Internal
• Trusted

How to think about them:

• External: traffic from a less trusted or customer-controlled source
• Internal: traffic from a system your team operates
• Trusted: traffic you consider highly reliable

If you are unsure, start with External. It is the safest default because it avoids claiming more trust than you have actually established.

Frontend API contract

The app currently uses these endpoints:

GET /tenants/{tenant_id}/api-keys
POST /tenants/{tenant_id}/api-keys
PATCH /tenants/{tenant_id}/api-keys/{api_key_id}
DELETE /tenants/{tenant_id}/api-keys/{api_key_id}

How this connects to the rest of the system

• Events are displayed with a source_id.
• Entity state includes source_id.
• The overview page uses API key count as part of the ingest posture summary.

This means API keys are part of the ingest identity model, not just an admin credential inventory.

A good first setup

For an early-stage team, a good first setup is:

• one key per major sending system
• clear labels such as Web app prod or Checkout service staging
• stable source_id values that do not change often

Avoid creating a new key for every minor deploy. The docs and UI are easier to understand when each key represents one stable source.