Developer guide
Signet tells you whether the browser in front of you is a trustworthy returning device, a new one, or something suspicious (bot, emulator, anonymising network, one device behind many accounts), and why, in plain English. You add one script tag, forward one field, and make one API call.
- Sign up (free, 1,000 assessments a month, no card) and copy your keys.
- Add the tag to the pages you want to protect. Mark the form with
data-signet. - On your server, read
signet_session_idfrom the form and callPOST /v1/assesswith your secret key. - Act on
decision: allow review deny. Showsummaryto your reviewers.
Base URL: https://signetsentry.com. Interactive API reference: /docs. Prefer to read code first? Download the sample ASP.NET project or jump to the live check of your own device.
1. Get your keys
Sign up (or call the API) and you receive two live keys and two sandbox keys:
| Key | Looks like | Where it goes |
|---|---|---|
| Public site key | pk_live_... | In your web page (data-site-key). Safe to expose; it can only submit device data. |
| Secret API key | sk_live_... | Your server only. Sent as Authorization: Bearer sk_live_.... Shown once; only a hash is stored. |
| Test keys | pk_test_... / sk_test_... | Sandbox: no quota, nothing stored, fixed outcomes. See Test mode. |
curl -X POST https://signetsentry.com/v1/signup -H "Content-Type: application/json" \
-d '{"name":"My Shop","email":"you@example.com"}'
# -> public_site_key (pk_live_...), secret_api_key (sk_live_...), test_keys { pk_test_..., sk_test_... }
Lost your secret key? Email support@signetsentry.com and we will issue a new one.
2. Add the tag
<script async src="https://signetsentry.com/v1/tag.js" data-site-key="pk_live_..."></script>
<!-- That's it. Any form marked data-signet gets a hidden signet_session_id field automatically: -->
<form data-signet action="/pay" method="post">
<input name="email" type="email">
<button>Pay</button>
</form>
The tag collects device attributes (canvas, WebGL, audio, fonts, screen, timezone, hardware, automation hints) and a few behaviour counts (it never reads what is typed), sends them to Signet and gets back an opaque session id. It adds a hidden signet_session_id field to every form[data-signet], including forms your framework adds later. Options on the script tag: data-site-key, data-api (override the API origin), data-auto="false" (wait for Signet.collect()), data-token="off" (don't persist a per-browser token), data-test-outcome (sandbox only).
You must tell visitors you use device-based fraud prevention (see the privacy policy template and Privacy & deletion), and get consent first where the law requires it.
3. Send the session id to your server
With data-signet the id arrives with the form post. For single-page apps or fetch calls, ask the tag:
// Not using a plain form post (fetch / SPA)? Ask the tag for the id:
const sessionId = await Signet.getSessionId();
await fetch("/api/checkout", { method: "POST", headers: { "Content-Type": "application/json" },
body: JSON.stringify({ sessionId, email }) });
Session ids can be assessed for 24 hours after they are created. Each id can be assessed more than once (for example at login, then at checkout).
4. Ask for a verdict: POST /v1/assess
One call: session id in, decision and explanation out. event is one of checkout, login, signup, password_reset, details_change, pageview. email is optional: it is turned into a salted hash and used as the account id for velocity checks (many accounts on one device); it is never stored in clear. You can pass your own account_id instead. amount, currency and profile are optional.
curl -X POST https://signetsentry.com/v1/assess \
-H "Authorization: Bearer $SIGNET_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"session_id":"s_...","event":"checkout","email":"buyer@example.com","amount":49.90,"currency":"USD"}'// Server side (Node 18+). Never call this from the browser: it needs your SECRET key.
const res = await fetch("https://signetsentry.com/v1/assess", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SIGNET_SECRET_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ session_id: sessionId, event: "checkout", email, amount: 49.9, currency: "USD" }),
});
const verdict = await res.json(); // { decision: "allow" | "review" | "deny", risk_score, summary, explanation, ... }// Plain HttpClient (no dependencies). The typed client in the sample project wraps exactly this.
using var http = new HttpClient { BaseAddress = new Uri("https://signetsentry.com") };
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("SIGNET_SECRET_KEY"));
var res = await http.PostAsJsonAsync("/v1/assess", new { session_id = sessionId, @event = "checkout", email, amount = 49.90m, currency = "USD" });
res.EnsureSuccessStatusCode();
var verdict = await res.Content.ReadFromJsonAsync<JsonElement>();
var decision = verdict.GetProperty("decision").GetString(); // "allow" | "review" | "deny"// Program.cs
builder.Services.AddSignet(o => builder.Configuration.GetSection("Signet").Bind(o));
// handler
var v = await signet.AssessAsync(new AssessRequest(sessionId) { Event = "checkout", Email = email, Amount = 49.90m });
if (v.IsDeny) return Results.Problem("Declined");
if (v.IsReview) HoldForManualReview(order, v.Summary);Complete example: Node / Express in about 20 lines
import express from "express";
const app = express();
app.use(express.urlencoded({ extended: false }));
app.post("/pay", async (req, res) => {
const r = await fetch("https://signetsentry.com/v1/assess", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SIGNET_SECRET_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ session_id: req.body.signet_session_id, event: "checkout",
email: req.body.email, amount: Number(req.body.amount) }),
});
if (!r.ok) return res.send("Order placed"); // fail open if the risk check is unavailable
const v = await r.json();
if (v.decision === "deny") return res.status(402).send("Payment declined");
if (v.decision === "review") return res.send("Order on hold for review: " + v.summary);
res.send("Order placed");
});
app.listen(3000);
The response
{
"session_id": "s_...", "visitor_id": "v_...", "event_type": "PAYMENT",
"risk_score": 60, "decision": "review", "action": "review", "profile": "default",
"thresholds": { "review": 40, "deny": 75 },
"summary": "Review (score 60): this looks like a new device on an anonymised network.",
"explanation": ["The request came from a datacenter or hosting network.", "..."],
"reason_codes": ["IP_DATACENTER", "IP_VPN", "NEW_DEVICE_AT_PAYMENT"],
"reasons": [{ "code": "IP_DATACENTER", "description": "...", "score": 25, "rule_id": "ip-datacenter" }],
"visitor": { "is_new": true, "seen_count": 1, "match_type": "new", "match_confidence": 1.0 },
"signals": { "ip": {...}, "device": {...}, "behavior": {...} }
}
The older GET/POST /v1/sessions/{session_id} endpoints return the same assessment (without action); /v1/assess simply accepts the form field name as it is and maps friendly event names.
5. Act on the decision and the reason codes
| decision | Meaning | Typical action |
|---|---|---|
| allow | Score below the review threshold (default 40). | Proceed normally. |
| review | Score 40 to 74, or a rule with a review floor matched. | Step up: ask for 2FA or a captcha, hold the order for a manual look, or send a verification email. Show summary to the reviewer. |
| deny | Score 75 or more, or a rule with a deny floor matched (for example a device you labelled fraud). | Block or cancel, and log the reason_codes. |
reason_codes are stable identifiers you can branch on (for example always step up on VELOCITY_MANY_ACCOUNTS_PER_DEVICE). explanation is a list of plain-English sentences safe to show to your support and risk team (not to the customer). The full list of codes is in How scores are calculated.
How scores are calculated
Signet uses transparent, additive rules, not a black box. Each rule that matches adds (or subtracts) points. The points are summed and clamped to 0–100.
Rules in the same group count once (the highest one wins) so related signals are not double counted.
decision = deny if score ≥ 75, else review if score ≥ 40, else allow. A rule with a decision floor can raise the decision regardless of score.
The table below is generated live from the rules the service is running right now (/v1/scoring), so it can't drift from the code. Your account can change any of it with profiles or custom rules.
| Reason code | What it means | When it fires | Points |
|---|---|---|---|
| Loading the current rules… | |||
Base score: 0. Rows sharing a group (for example three VELOCITY_* tiers) are alternatives: only the highest matching one applies.
Worked example
A new device (NEW_DEVICE_AT_PAYMENT +10) on a datacenter IP (IP_DATACENTER +25) behind a VPN range (IP_VPN +15) with a software WebGL renderer (DEVICE_SOFTWARE_RENDERER +10) scores 60: review. Add DEVICE_WEBDRIVER (+40) and the score is 100: deny. A trusted, returning device earns negative points (RETURNING_DEVICE −10, DEVICE_PREVIOUSLY_TRUSTED −15).
Scoring profiles
Different events deserve different strictness. A profile is a named set of overrides layered on your rules: thresholds, base_score, and per-rule score or enabled. Everything you don't mention is inherited. Up to 25 profiles per account; names are lower-case letters, digits, - and _.
# Create a stricter profile for payments
curl -X PUT https://signetsentry.com/v1/profiles/checkout \
-H "Authorization: Bearer $SIGNET_SECRET_KEY" -H "Content-Type: application/json" \
-d '{"description":"Stricter for payments","thresholds":{"review":30,"deny":60},
"rules":{"ip-vpn":{"score":30},"device-bot-ua":{"enabled":false}}}'
# Use it for one call (query string or body field)...
curl -X POST "https://signetsentry.com/v1/assess?profile=checkout" ...
# ...or make it the default for the whole account
curl -X PUT https://signetsentry.com/v1/profiles/checkout -d '{"is_default":true}' ...
GET /v1/profiles,GET|PUT|DELETE /v1/profiles/{name},GET /v1/profiles/{name}/effective(the merged rules, so you can preview what it does).- Choose per call with
?profile=nameor aprofilefield in the body; otherwise the account's default profile is used ("is_default": true), otherwise your rules as they are. - Every response includes
profile(the one used) andthresholds. An unknown profile returns 404profile_not_found, so typos never silently fall back to weaker rules. - The sample project shows passing a profile with
Signet:Profile.
Test mode
Build and test your whole integration without real traffic. Use the pk_test_ / sk_test_ keys from signup (or POST /v1/test-keys with your live secret key to create a pair). Sandbox calls use no quota and store nothing.
# Sandbox keys never use quota and store nothing. Magic session ids give fixed outcomes:
curl -X POST https://signetsentry.com/v1/assess -H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" -d '{"session_id":"test_deny","event":"checkout"}'
Session id (or data-test-outcome) | Result |
|---|---|
test_allow | allow score 5, RETURNING_DEVICE |
test_review | review score 50, datacenter + VPN + new device |
test_deny | deny score 100, Tor + automation + many accounts |
With a test public key the tag can pick the outcome for you, so your front end produces each result without any server tricks:
<script async src="https://signetsentry.com/v1/tag.js"
data-site-key="pk_test_..." data-test-outcome="review"></script>
Test secret keys work with /v1/assess, /v1/sessions, /v1/account and /v1/feedback (everything else needs the live key, 403 test_key_not_allowed), and responses carry "test_mode": true.
Outbound webhooks
Get told the moment something needs attention instead of polling. Register one HTTPS URL; Signet POSTs a signed JSON event for each assessment decision you subscribe to (default review and deny).
curl -X PUT https://signetsentry.com/v1/webhook \
-H "Authorization: Bearer $SIGNET_SECRET_KEY" -H "Content-Type: application/json" \
-d '{"url":"https://example.com/hooks/signet","events":["review","deny"]}'
# -> {"signing_secret":"whsec_..."} (shown once; add "rotate_secret": true to rotate)
curl -X POST https://signetsentry.com/v1/webhook/test -H "Authorization: Bearer $SIGNET_SECRET_KEY"
Delivery: POST application/json with headers X-Signet-Signature: t=<unix>,v1=<hex>, X-Signet-Event and X-Signet-Delivery. Any 2xx counts as delivered; failures are retried twice (after about 5 s and 30 s). Make your handler idempotent on id. Targets must be public HTTPS URLs.
{
"id": "evt_8f2c1a...",
"type": "assessment.deny", // assessment.review | assessment.deny | assessment.allow
"created_at": "2026-11-19T15:04:05Z",
"test": false,
"data": {
"session_id": "s_...", "visitor_id": "v_...", "account_id": "e_...", "event_type": "PAYMENT",
"decision": "deny", "risk_score": 100, "profile": "default",
"reason_codes": ["IP_TOR_EXIT", "DEVICE_WEBDRIVER"],
"summary": "Deny: ...", "explanation": ["...", "..."]
}
}
Verify the signature
v1 is the hex HMAC-SHA256, keyed with your signing secret, of the string "<t>.<raw request body>". Use the raw bytes (not re-serialised JSON), compare in constant time and reject old timestamps.
import crypto from "node:crypto";
app.post("/hooks/signet", express.raw({ type: "application/json" }), (req, res) => {
const parts = Object.fromEntries(req.get("X-Signet-Signature").split(",").map(p => p.split("=")));
const expected = crypto.createHmac("sha256", process.env.SIGNET_WEBHOOK_SECRET)
.update(`${parts.t}.${req.body}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
const ok = fresh && expected.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
if (!ok) return res.sendStatus(400);
const event = JSON.parse(req.body); // handle event.type, event.data ...
res.sendStatus(200);
});static bool Verify(string signatureHeader, string rawBody, string secret)
{
var p = signatureHeader.Split(',').Select(x => x.Split('=', 2)).ToDictionary(x => x[0], x => x[1]);
var mac = new HMACSHA256(Encoding.UTF8.GetBytes(secret))
.ComputeHash(Encoding.UTF8.GetBytes($"{p["t"]}.{rawBody}"));
var fresh = Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(p["t"])) < 300;
return fresh && CryptographicOperations.FixedTimeEquals(Convert.FromHexString(p["v1"]), mac);
}Feedback: teach Signet your outcomes
Label a session fraud (a chargeback, an abusive account) or legit (a confirmed good customer). Labels shape that device's reputation for your account only: a fraud-labelled device returns DEVICE_PREVIOUSLY_FRAUD next time and is denied; a trusted one earns negative points.
curl -X POST https://signetsentry.com/v1/feedback \
-H "Authorization: Bearer $SIGNET_SECRET_KEY" -H "Content-Type: application/json" \
-d '{"session_id":"s_...","label":"fraud","note":"chargeback 2026-11-02"}' # label: "fraud" | "legit"
Dashboard and suspicious-activity alerts
Log in with the email and password you chose at sign-up (set one for an existing account with your secret key or Gumroad license key on the same page). From the dashboard you can also create, edit and test scoring profiles, view and rotate your API keys, configure your webhook, and see your plan and usage. You get checks over time (stacked by decision), a score histogram, the top risk reasons, top countries and a usage-versus-quota gauge. At the top, a Suspicious activity panel explains in plain English what changed, with severity and a link to the matching checks:
- Deny or review spike compared with the period before.
- Devices with many accounts or emails.
- Velocity bursts from one IP or device.
- Datacenter, VPN or Tor traffic.
- Bot or emulator signals (automation, headless browsers, spoofed APIs).
- Impossible travel: one account seen in distant countries within a short time.
The same data is available at GET /v1/dashboard/summary and GET /v1/dashboard/activity (filters: decision, reason, country, visitor, ip, account, profile, min_score). Alerts are shown in the app; pair them with webhooks to be notified.
Quotas, rate limits and errors
| Plan | Price | Assessments / month |
|---|---|---|
| Free | $0 | 1,000 |
| Starter | $29 / month | 25,000 |
| Growth | $99 / month | 150,000 |
An assessment is one successful /v1/assess or /v1/sessions/{id} call. Collecting sessions with the tag, feedback, dashboard and account calls don't count. Quotas reset on the first of each month (UTC). Responses carry X-Quota-Limit and X-Quota-Remaining.
| HTTP | error | What to do |
|---|---|---|
| 400 | session_id_required, invalid_body | Fix the request. |
| 401 | missing_api_key, invalid_api_key | Send Authorization: Bearer sk_... (secret key, not the public one). |
| 402 | subscription_inactive | Payment past due: update your payment method (or resubscribe). Access returns automatically. |
| 403 | wrong_key_type, test_key_not_allowed | Use the secret key (not the public key), or the live key for this endpoint. |
| 404 | session_not_found, profile_not_found | Check the id / profile name. |
| 410 | session_expired | Sessions can be assessed for 24 hours. Collect a new one. |
| 429 | quota_exceeded | Monthly quota used. Upgrade or wait for the reset (see Retry-After). |
| 429 | rate_limited | Slow down and retry. |
Plan and billing
GET /v1/account returns your plan, subscription status (active, past_due, cancelled), period end and usage. Upgrade from /pricing; subscriptions are monthly memberships handled by Gumroad, and you manage or cancel them from the Gumroad receipt email. If you cancel, you keep your plan until the end of the paid period and then drop to the Free plan (nothing is deleted). If a payment fails, API calls return 402 until it is fixed.
Privacy, retention and deletion
- Signet is for fraud prevention only: no advertising, no cross-site tracking. Visitor ids are different for every customer account.
- Raw assessment data is kept for 90 days by default, then deleted automatically.
- Emails you pass are hashed; they are never stored in clear.
- Data-subject request:
DELETE /v1/visitors/{visitor_id}erases a device and its linked sessions and feedback. - You are responsible for disclosing the use of the tag and for lawful basis or consent in your jurisdiction. See the privacy policy and terms (templates, not legal advice).
curl -X DELETE https://signetsentry.com/v1/visitors/v_... -H "Authorization: Bearer $SIGNET_SECRET_KEY" # 204 No Content
Sample project (ASP.NET Core, .NET 10)
A runnable checkout page and minimal API that embeds the tag, posts the session id to its backend, calls Signet through a typed SignetClient and shows the decision with its explanation. It also shows passing a scoring profile and failing open.
Download signet-sample-aspnet.zip
unzip signet-sample-aspnet.zip && cd signet-sample-aspnet/Signet.Sample.Checkout
dotnet user-secrets set "Signet:PublicKey" "pk_test_..."
dotnet user-secrets set "Signet:SecretKey" "sk_test_..."
dotnet run # then open the printed URL (add ?outcome=review in sandbox mode)
Config lives in appsettings.json (Signet:BaseUrl defaults to this service) and secrets come from user secrets or environment variables (Signet__SecretKey). The client lives in its own NuGet-ready project (Signet.Client, dotnet pack to publish it to your own feed).
Why Signet vs legacy device-intelligence vendors
Established device-intelligence and fraud platforms are powerful, and some offer things Signet does not (see the honest limits below). Signet is built for teams that want to be live this afternoon. Comparing like with like, in general terms:
| Signet | Typical enterprise vendor | |
|---|---|---|
| Getting started | Self-serve sign-up, keys in seconds, free tier | Usually a sales conversation, contract and onboarding project |
| Pricing | Public: Free, $29, $99 a month, month-to-month | Often quote-based, annual commitments |
| Integration | One script tag, data-signet on a form, one API call | Often SDKs, profiling pages and multi-step server flows |
| Explaining a decision | Plain-English summary and explanation on every response, plus stable reason codes | Varies; frequently scores and codes needing interpretation |
| Rules | Open and editable: see every rule and its points, override per account or per event with profiles | Varies; often managed by the vendor or behind a separate rules product |
| Testing | Sandbox keys and magic sessions for allow/review/deny | Varies |
| Notifications | HMAC-signed webhooks and an in-app suspicious-activity panel | Varies |
| Data location and control | Per-account visitor ids, automatic retention, one-call deletion | Varies |
Try it: see your own device's score
This runs the real tag in your browser, then asks Signet for a verdict on this page's demo account, exactly as a merchant's server would. Nothing you type here is read.
loading the tag…-