The knownprint demo

1. 1

   Step 1

   One proxy rule

   Your nginx or Caddy forwards /kp/ to knownprint, so the agent, its endpoints and the cookie are all on your own domain. Only the kp_t cookie leaves your server; your session cookies stay where they are.

   # Inside your site's TLS server block. The full recipe adds the bundle
   # location, the cache headers and /.well-known/knownprint.json.
   # Signup (coming) gives you $knownprint_upstream and the proxy secret.
   include /etc/knownprint/proxy-secret.conf;
   
   location = /kp/agent.js {
       proxy_pass $knownprint_upstream;
       proxy_set_header X-Knownprint-Proxy-Secret $knownprint_proxy_secret;
       proxy_set_header X-Knownprint-Client-Ip $remote_addr;
       proxy_set_header X-Knownprint-Forwarded-Host $host;
       proxy_set_header Cookie "";
       proxy_hide_header Set-Cookie;
   }
   
   location ^~ /kp/ {
       proxy_pass $knownprint_upstream;
       proxy_set_header X-Knownprint-Proxy-Secret $knownprint_proxy_secret;
       proxy_set_header X-Knownprint-Client-Ip $remote_addr;
       proxy_set_header X-Knownprint-Forwarded-Host $host;
       proxy_set_header X-Knownprint-Net "";
       # only kp_t leaves your server ($knownprint_cookie, knownprint-map.conf)
       proxy_set_header Cookie $knownprint_cookie;
   }

   import knownprint

2. 2

   Step 2

   One script tag, and the request id posted with the form

   The agent reads the browser and hands the page a request id (requestId) and its expiry, never the visitor id, the confidence or a verdict to tamper with. The page never learns which browser it is; your backend does. Your form posts the request id (kp_request_id) with the signup.

   <script src="/kp/agent.js" defer></script>
   
   // PUBLIC_KEY is your environment's public key (pk_live_...).
   const agent = await window.knownprint.load({ pk: PUBLIC_KEY, profile: 'security' });
   const { requestId } = await agent.identify();
   form.elements.kp_request_id.value = requestId; // posted with the form

3. 3

   Step 3

   One call in your backend, in shadow mode first

   Read the event with your secret key, then ask for a verdict. Shadow mode records what knownprint would have done and blocks nothing. Switch to enforce after a week of verdicts.

   GET /v1/events/evt_q3vx7k2mz4rb6nw5tc2ehj7ypd
   Authorization: Bearer <your secret key>
   
   POST /v1/check
   Authorization: Bearer <your secret key>
   Content-Type: application/json
   
   {"request_id": "evt_q3vx7k2mz4rb6nw5tc2ehj7ypd", "action": "signup", "shadow": true}

   app.post('/signup', kp.require('signup', options), signupHandler);

{
  "action": "deny",
  "score": 0, coming
  "reasons": ["visitor_blocklisted", "shadow_mode"],
  "list_hits": [
    {
      "list": "blocklist",
      "subject_type": "visitor",
      "subject": "v_m5tk2wq7xr3bz6ne4yc2hv7pja",
      "via": "token"
    }
  ],
  "identity": {
    "visitor_id": "v_m5tk2wq7xr3bz6ne4yc2hv7pja",
    "match_type": "token",
    "confidence": 1,
    "anonymity_set_size": 1,
    "device_cluster_id": null,
    "cluster_confidence": null
  },
  "velocity": {
    "accounts_visitor_5m": 0,
    "accounts_visitor_1h": 0,
    "accounts_visitor_24h": 0,
    "ips_visitor_5m": 1,
    "ips_visitor_1h": 1,
    "ips_visitor_24h": 2,
    "signups_ip_5m": 1,
    "signups_ip_1h": 1,
    "signups_ip_24h": 3,
    "events_ip_5m": 2,
    "events_ip_1h": 4,
    "events_ip_24h": 9
  },
  "human_review_required": true,
  "shadow": true,
  "check_id": "chk_b7zq2m4kx6vn3rt5wy2ech7pdl",
  "request_id": "evt_q3vx7k2mz4rb6nw5tc2ehj7ypd"
}

Get early access

Get early access