This quickstart verifies Trace events in a Rails (or any Rack) app with the trace-device gem. It uses only the standard library.
Tested in CI
Passes its tests on Ruby 3.3, against the same test vectors as the other SDKs. It has not yet been used in a production Rails 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). Ruby 3.0 or later.
- 1
Install the SDK
Terminalbundle add trace-deviceTerminalexport TRACE_SECRET_KEY=sk_... export TRACE_ENDPOINT=https://id.example.com - 2
Verify the event
rubyclient = Trace::Client.new(ENV["TRACE_SECRET_KEY"], ENV["TRACE_ENDPOINT"], timeout: 1.5) event = begin client.get_event(params[:eventId]) rescue Trace::VerifyError => e Rails.logger.warn("Trace check skipped: #{e.code}") # fail open nil end if event && event["suspectScore"] >= 60 render json: { error: "blocked" }, status: :forbidden endThe event is a
Hashwith the same fields as the API response.
Or use the guard
Trace::Rack::Guard is Rack middleware that reads the event id from the X-Trace-Event-Id header, a JSON body or a form body, verifies it, and puts the event in env["trace.event"]. It guards only the paths you list, and the body stays readable.
# config/application.rb
config.middleware.use Trace::Rack::Guard, paths: ["/signup", %r{\A/api/}], reject_score: 80, fail_open: true# in a controller
event = request.env["trace.event"] # nil only with fail_open when Trace was unreachableTo decide inside a controller instead, call Trace::Guard.new(reject_score: 80).check(event_id); it returns an outcome with ok?, event, status and body.
The guard answers 400 for a missing or invalid event, 403 when the score is at or above reject_score (or reject returns true), 503 when Trace cannot be reached and 500 for a bad key or missing configuration. fail_open: true only covers the unreachable case; a wrong key never fails open.
Webhooks and sealed results
# Pass the raw body, before any JSON parsing.
payload = Trace.verify_webhook(request.raw_post, request.headers["X-Signature"], ENV["TRACE_WEBHOOK_SECRET"])
# Sealed results (SEALED_RESULTS_KEY on the server), no API call.
event = Trace.unseal_event_result(params[:sealedResult], ENV["TRACE_SEALED_KEY"])Errors are Trace::VerifyError, Trace::WebhookError and Trace::SealedError, each with a code. Deliveries are at least once: dedupe on payload["id"].