This quickstart verifies Trace events in an ASP.NET Core app with the TraceDevice and TraceDevice.AspNetCore NuGet packages. They have no third-party dependencies.
Tested in CI
Builds and passes its tests on .NET 8, against the same test vectors as the other SDKs. It has not yet been used in a production app, so start the guard in shadow mode.
Before you start
You need a secret key (sk_...) from the dashboard's Keys page and a frontend that sends an eventId (see the Web quickstarts). .NET 8 or later.
- 1
Install the SDK
Terminaldotnet add package TraceDevice dotnet add package TraceDevice.AspNetCoreTerminalexport TRACE_SECRET_KEY=sk_... export TRACE_ENDPOINT=https://id.example.com - 2
Verify the event
csharpusing TraceDevice; var client = new TraceClient(Environment.GetEnvironmentVariable("TRACE_SECRET_KEY")!, Environment.GetEnvironmentVariable("TRACE_ENDPOINT")!, TimeSpan.FromMilliseconds(1500)); TraceEvent? ev = null; try { ev = await client.GetEventAsync(eventId); } catch (VerifyException e) { logger.LogWarning("Trace check skipped: {Code}", e.Code); // fail open } if (ev is { SuspectScore: >= 60 }) return Results.StatusCode(403);TraceEventcarriesVisitorId,SuspectScore,Reasons,Signals(withDetected("multiAccount")) andRaw, the full JSON, for fields it does not name.
Or use the guard
The middleware reads the event id from the X-Trace-Event-Id header, a JSON body or a form body, verifies it, and stores the event on the request. The body stays readable.
using TraceDevice;
using TraceDevice.AspNetCore;
// Middleware: guard POST, PUT, PATCH and DELETE under /api
app.UseTraceGuard(new TraceGuardOptions { RejectScore = 80, FailOpen = true },
ctx => ctx.Request.Path.StartsWithSegments("/api"));
app.MapPost("/api/signup", (HttpContext ctx) =>
{
var ev = ctx.GetTraceEvent(); // null only with FailOpen when Trace was unreachable
return Results.Ok(ev?.VisitorId);
});
// Or guard a single minimal-API endpoint
app.MapPost("/signup", handler).RequireTrace(new TraceGuardOptions { RejectScore = 80 });The guard answers 400 for a missing or invalid event, 403 when RejectScore or Reject says so, 503 when Trace cannot be reached and 500 for a bad key or missing configuration. FailOpen = true only covers the unreachable case; a wrong key never fails open.
Webhooks and sealed results
// Pass the raw body, before any JSON parsing.
var payload = TraceWebhooks.Verify(rawBodyBytes, Request.Headers["X-Signature"], webhookSecret);
// Sealed results (SEALED_RESULTS_KEY on the server), no API call.
var ev = TraceSealed.Unseal(sealedResult, sealedKey);Errors are VerifyException, WebhookException and SealedException, each with a Code. Deliveries are at least once: dedupe on payload.Id.