SDK documentation

Quickstart

1. Create a public key.

   Sign in to your API keys page and add each exact website origin that can submit browser assessments. Copy the key when it is shown.

2. Load the SDK.

   Add the script to your page. Loading it alone does not collect signals or send an assessment.

   HTMLCopy

   <script src="https://identifai.ca/v1.js"></script>

3. Assess a meaningful event.

   Call the SDK after it has loaded and when you have the appropriate permission to collect device signals. Keep user IDs pseudonymous; never use an email address or password.

   JavaScriptCopy

   const result = await Identifai.assess({
     apiKey: "pk_your_public_key",
     event: "signup",
     userId: "customer_123" // optional account reference
   });
   
   console.log(result.visitor_id, result.risk_score);

Assessment API

Send JSON with a public API key, an event name, and browser signals. The server records its own request time, source IP, user agent, and customer. A client-supplied IP field is never authoritative.

curl -X POST 'https://identifai.ca/v1/assess' \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://your-website.example' \
  --data '{
    "api_key": "pk_your_public_key",
    "event": "signup",
    "user_id": "customer_123",
    "signals": {
      "language": "en-CA",
      "timezone": "America/Vancouver",
      "screen": {"width": 1440, "height": 900},
      "colorDepth": 24,
      "hardwareConcurrency": 8,
      "platform": "MacIntel"
    }
  }'

This minimal example illustrates the request format. Low-information signals may not be sufficient to recognize a device. API keys are public; Origin checks are a browser control, not proof of a caller’s identity.

Reading the response

{
  "visitor_id": "dev_example",
  "confidence": 0.91,
  "risk_score": 30,
  "returning": true,
  "signals": {
    "account_velocity": false,
    "ip_velocity": false,
    "device_reuse": true
  }
}

visitor_id

An internal device identifier scoped to your customer. It remains stable when a likely match is found.

confidence

A heuristic estimate from 0 to 1. It is not a calibrated probability or a guarantee that two visits share a device.

risk_score

A rule-based score from 0 to 100. Review its reasons in the dashboard; a low score does not prove that activity is safe.

returning

Whether this assessment matched a previously seen device in your workspace.

signals

Risk indicators triggered by the assessment. These are separate from raw browser signals.

Matching & risk

Identifai compares normalized signals against a bounded set of recently seen devices in the same customer workspace. WebGL and canvas-derived signals carry more weight; display, timezone, hardware, and language contribute supporting evidence. Missing or common signals alone are not enough to make a strong match.

The risk engine evaluates account reuse, signup bursts, IP velocity, device changes, and a workspace’s manual suspicious flag. Individual rules add points, capped at 100, and the dashboard retains an explanation for each contribution.

Use device assessments as one input alongside your own account and transaction context. Shared household devices, public computers, privacy protections, and changing networks can produce false positives or missed matches. The MVP does not provide IP reputation, VPN detection, legal identity verification, or a machine-learning fraud probability.

Errors & limits

The SDK rejects its promise on network errors, timeouts, and non-success API responses. Handle failures explicitly. It does not automatically retry, because repeating a signup event would affect velocity counts.

try {
  const result = await Identifai.assess({
    apiKey: "pk_your_public_key",
    event: "login"
  });
  // Apply your own review policy using result.
} catch (error) {
  // Apply your application's fallback policy.
  console.error("Assessment unavailable");
}

Privacy & deployment

The SDK observes normal browser characteristics without asking for location, contacts, files, passwords, or other domains’ cookies. Include the collection in your own privacy information and configure your consent flow for your use case.

Customer user IDs and source IPs are stored as keyed hashes for matching. The dashboard displays pseudonymous account references and masked IP labels. Browser signals and assessment history are retained for 365 days under the current configuration. Workspace controls can delete data for an account or a device.

Identifai’s public pages offer optional Google Analytics. The assessment SDK does not load Google Analytics, and dashboard activity is excluded. See the privacy overview for more detail.