SDK Event Submission

Most events that matter for fraud happen on the device: the login, the session, the gameplay round, the timing telemetry that separates a person from a script. The device lane sends them without putting an API key in a browser. Your backend mints a short-lived credential scoped to one user; the app posts events with it.

Flow

Mint a monitoring credential

Your backend calls POST /v3/events/sdk-token/ with your API key and the user’s vendor_data.

Submit from the device

The app posts to POST /v1/events/ (or POST /v1/events/batch/) with the X-Monitoring-Token header.

Rules run as usual

The event is enriched, rolled up and evaluated by exactly the same rules as a server-submitted one.

Minting a credential

curl -X POST https://verification.didit.me/v3/events/sdk-token/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user_391",
    "allowed_event_categories": ["auth", "session", "gameplay"],
    "ttl_seconds": 900,
    "max_uses": 1000,
    "bind_to_origin": "https://operator.example"
  }'

{
  "monitoring_token": "…",
  "expires_at": "2026-08-31T21:00:00Z",
  "allowed_event_categories": ["auth", "session", "gameplay"],
  "max_uses": 1000,
  "bind_to_origin": "https://operator.example"
}

Field	Default	Notes
`vendor_data`	required	The subject every event submitted with this credential belongs to.
`entity_type`	`individual`	`individual` or `company`.
`allowed_event_categories`	all	Narrow what a leaked credential could write.
`ttl_seconds`	900	60 - 86400.
`max_uses`	1000	One use per event, not per request.
`bind_to_origin`	none	When set, the browser `Origin` must match exactly.

Submitting

curl -X POST https://verification.didit.me/v1/events/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "session-abc-login-1",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "session": { "session_id": "web-session-abc", "sequence": 1 },
    "device_context": { "fingerprint": "didit-fp-v2:a8c1" },
    "payload": { "method": "password" }
  }'

Note what the payload does not carry: no API key, and no subject. Both are enforced server-side.

What the server enforces

Subject binding. The credential is scoped to one vendor_data at mint time. A subject block in the request body is overwritten, so a tampered client cannot write to another user’s timeline.
Network context. The IP address, user agent, accept-language and origin are derived from the request, and those server-derived values win over any client hint for rule evaluation. Rule evidence records the difference as a field source.
Category scope. A credential scoped to session cannot submit a payment event; it is rejected with 400.
Use budget. A batch spends one use per event, so a 500-event batch cannot slip past a 10-use credential as a single use.
Origin binding. When bind_to_origin is set, a request whose Origin does not match is refused - including one with no Origin at all.

Batching

curl -X POST https://verification.didit.me/v1/events/batch/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "events": [ { "…": "…" }, { "…": "…" } ] }'

Up to 500 events per flush, with the same per-item outcomes as the server batch endpoint. A good default flush is 25 events, 5 seconds, or page/app backgrounding.

What to drop under backpressure

If you have to shed events, shed the cheap ones. These are safe to drop: session.page_view · session.sdk_heartbeat · session.sdk_loaded · session.device_seen · session.bot_signal_observed · bonus.promotion_viewed · affiliate.referral_clicked These are not - flush them first: every security, payment, dispute and responsible_gambling event, plus gameplay.bet_placed, gameplay.bet_settled and gameplay.p2p_settlement. The list endpoints return the same classification per event as is_droppable, so a client can be driven by it rather than by a hardcoded copy.

Header compatibility

The canonical header is X-Monitoring-Token. X-Transaction-Token is accepted as a temporary alias so an app that already holds a transaction credential path can migrate incrementally.

The alias is transitional and will be removed before the events API reaches general availability. Send X-Monitoring-Token in new code.

Choosing a lane

	Device lane	Server lane
Endpoint	`POST /v1/events/`	`POST /v3/events/`
Auth	`X-Monitoring-Token`	`x-api-key`
Subject	Bound to the credential	In the payload
Best for	Logins, sessions, gameplay, telemetry	Payments, disputes, ledger-derived events, backfills

Both produce identical event records and run identical rules. Use the server lane whenever no end user is present.

Event ingestion

The envelope, categories, retention and idempotency.

Rules on events

Velocity, ratio, sequence and correlation rules.

Getting Started

Features

Reference

Console

Flow

Minting a credential

Submitting

What the server enforces

Batching

What to drop under backpressure

Header compatibility

Choosing a lane

Next

Event ingestion

Rules on events

​Flow

​Minting a credential

​Submitting

​What the server enforces

​Batching

​What to drop under backpressure

​Header compatibility

​Choosing a lane

​Next

Event ingestion

Rules on events

Flow

Minting a credential

Submitting

What the server enforces

Batching

What to drop under backpressure

Header compatibility

Choosing a lane

Next