Ruby SDK

sentriq is a server-only gem — it holds a secret key and must never run in browser-facing code. For browser-side tracking, see the Browser SDK. Framework-neutral — no Rails/ActiveSupport dependency; Rails integration will live in a separate sentriq-rails gem built on top of this one. Requires Ruby 3.1+, zero runtime dependencies (Net::HTTP, json, and openssl are all standard library). Not yet published to RubyGems.org — install via a local path or a locally-built .gem file until a release process exists.

Install

gem install sentriq

Not yet resolvable from RubyGems.org — see § Publication status below for the real, current install path.

Initialize

require "sentriq"

client = Sentriq::Client.new(
  secret_key: ENV.fetch("SENTRIQ_SECRET_KEY"),
  # Optional. Defaults to the hosted Sentriq API.
  api_url: ENV["SENTRIQ_API_URL"],
  # Optional. Defaults to 10 seconds.
  timeout: 10,
  # Optional. Automatic retries for idempotent GET requests only. Default 2.
  max_retries: 2
)

Resources

client.events.retrieve(event_id)
client.events.list(environment_id, page: 1)
client.events.submit_outcome(event_id, label: :legitimate)
client.events.list_outcomes(event_id)

client.devices.retrieve(device_id)
client.devices.list(environment_id)
client.devices.list_events(device_id)
client.devices.list_accounts(device_id)
client.devices.list_signals(device_id)
client.devices.list_resolutions(device_id)
client.devices.trust(environment_id, external_account_id, device_id)
client.devices.revoke_trust(environment_id, external_account_id, device_id)

client.accounts.list_devices(environment_id, external_account_id)

client.risk.list(environment_id)

client.network.list(environment_id)

client.webhooks.verify_signature(raw_body, timestamp, signature, secret)

Errors

begin
  client.events.retrieve(event_id)
rescue Sentriq::AuthenticationError => e
  # 401
rescue Sentriq::NotFoundError => e
  # 404
rescue Sentriq::ValidationError => e
  # 422 — e.fields
rescue Sentriq::RateLimitError => e
  # 429 — e.retry_after
rescue Sentriq::ApiError => e
  # any other 4xx/5xx — e.status, e.request_id, e.code
rescue Sentriq::TransportError => e
  # network failure — e.timeout?
end

A real exception hierarchy rooted at Sentriq::Error, matching Node/PHP/Java/.NET's own convention rather than Go's flat sentinel-error style.

Retries

A GET request retries automatically (bounded exponential backoff) on a network error, timeout, 429, or 5xx, honoring Retry-After (seconds or an HTTP-date). Mutations (POST/DELETE) are never automatically retried — this API has no generic idempotency-key mechanism today, so blindly retrying a mutation could double-apply it. An Interrupt/SignalException raised during the retry-backoff sleep is never rescued or swallowed.

Webhook signatures

valid = client.webhooks.verify_signature(raw_body, timestamp, signature, webhook_secret)

HMAC-SHA256 over the same canonical string as every other SDK, compared with OpenSSL.fixed_length_secure_compare — constant-time, not a plain string equality check.

Threading / client reuse

A Sentriq::Client is safe for normal concurrent use by application threads — it holds no mutable per-request state, and a fresh Net::HTTP connection is opened per request rather than sharing one across calls. Construct one client and reuse it.

Version compatibility

Ruby 3.1+. Zero runtime dependencies.

Publication status

Not published to RubyGems.org — no release process exists for this gem yet. Reference it via a path:/git: Gemfile entry from a checkout of this repository, or build and install a local .gem file. gem install sentriq above is this gem's real, intended install command once published — not a claim that it resolves today.