# WhorlID

> Device identification API for fraud prevention. Recognizes returning browsers
> without cookies by scoring ~25 technical signals (canvas, WebGL, audio, fonts,
> hardware, locale) against every device a project has seen. Built for fraud
> prevention; forbidden for ad tracking. Visitor ids are scoped per project:
> the same physical device on two customers gets two unrelated ids.

## Quickstart (browser)

Add before the closing </body> tag:

    <script src="https://api.whorlid.com/v1/fp.js"></script>
    <script>
      fpjs.load({ publicKey: 'pk_live_...' })
        .then(fp => fp.get())
        .then(result => {
          // result.requestId is the only field to send to your backend
        });
    </script>

The public key (pk_...) is safe to expose in client code. The browser result
is a hint, not a proof: always verify server side.

## Server-side verification

    GET https://api.whorlid.com/v1/events/{requestId}
    Authorization: Bearer sk_live_...

The secret key (sk_...) must stay on the server, in an environment variable.
Response (JSON):

    {
      "requestId": "uuid",
      "visitorId": "uuid",          // stable device id within this project
      "decision": "match",           // match | new | low | ambiguous
      "similarity": 0.97,            // 0..1 match evidence strength
      "isReturning": true,
      "highConfidence": true,
      "isBot": false,
      "botScore": 0.04,              // 0..1 automation likelihood
      "threatLevel": "low",          // low | medium | high
      "country": "IE",
      "isDatacenter": false,
      "timestamp": "ISO-8601"
    }

## Suggested policy

- decision === 'match' && !isBot: known returning device
- isBot || threatLevel === 'high' || isDatacenter: challenge or manual review
- otherwise: proceed, store visitorId for pattern analysis (e.g. count
  accounts per visitorId at signup to stop trial abuse)

## Keys

Create a project and both keys in the dashboard: http://localhost:3000/dashboard
(public key for the browser agent, secret key for event verification).

## Plans

- Free: 16,000 identifications / month, $0
- Starter: 30,000 / month, $19
- Growth: 75,000 / month, $49
- Enterprise: custom volume and terms, http://localhost:3000/contact

10% grace above quota, then HTTP 429 { "error": "usage_limit_exceeded" }.

## Honest limits

Identification is probabilistic. Hardened anti-fingerprinting browsers (Tor,
aggressive privacy modes) randomize signals and defeat matching by design.
Treat results as strong evidence, not proof of identity; combine with your
own account signals.

## Links

- Docs: http://localhost:3000/docs
- Live demo: http://localhost:3000/demo
- Articles: http://localhost:3000/content
- Privacy and retention: http://localhost:3000/privacy (raw signals 30 days, events 90)
- Contact: http://localhost:3000/contact