Ruby and Rails

Verify events in Rails or any Rack app.

5 minutes

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. 1

    Install the SDK

    Terminal
    bundle add trace-device
    Terminal
    export TRACE_SECRET_KEY=sk_...
    export TRACE_ENDPOINT=https://id.example.com
  2. 2

    Verify the event

    ruby
    client = 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
    end

    The event is a Hash with 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.

ruby
# config/application.rb
config.middleware.use Trace::Rack::Guard, paths: ["/signup", %r{\A/api/}], reject_score: 80, fail_open: true
ruby
# in a controller
event = request.env["trace.event"] # nil only with fail_open when Trace was unreachable

To 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

ruby
# 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"].

Frontends

Next steps

Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.