Browser Fingerprint API Documentation

Collection example

Upload only after the user understands and agrees to what is submitted. This example sends a single UA field to demonstrate the protocol; it is not a complete browser assessment.

// Run from a page on the same origin as BrowserCheak.
const schema = await fetch('/api/fingerprint/schema').then(r => r.json());

// This minimal example uploads only a User Agent observation.
const sessionResponse = await fetch('/api/fingerprint/session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ tier: 'basic' })
});
if (!sessionResponse.ok) throw new Error('Session request failed');
const session = await sessionResponse.json();

const response = await fetch('/api/fingerprint/collect', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sessionId: session.sessionId,
    nonce: session.nonce,
    tier: 'basic',
    components: [{
      key: 'navigator', label: 'Browser', version: 1,
      tier: 'basic', status: 'ok', confidence: 'medium',
      durationMs: 0, value: { userAgent: navigator.userAgent }
    }]
  })
});
if (!response.ok) throw new Error('Report request failed');
const report = await response.json();
// report.id, createdAt, expiresAt, components, scores, findings, transport
// Missing signals in this minimal example limit report interpretation.

Components and responses

Components contain key, label, version, tier, status, value, durationMs and confidence. Status is ok, protected, unsupported, blocked, timeout or error. Confidence is high, medium, low or unknown. Use the schema endpoint for accepted component keys.

Reports contain id, createdAt, expiresAt, tier, schemaVersion, ruleVersion, scores, automationLevel, confidence, summary, findings, components and transport. Scores are heuristics from the current rules, not population uniqueness or real-world tracking probabilities.

Retention, limits and access

Default aggregate limits per source are 60 API requests per minute, 1,000 per 24 hours and 4 concurrent requests. Session creation and report submission each allow 6 per minute and 60 per 24 hours. A source can hold 3 unused sessions. Sessions expire after 10 minutes and successful submission consumes the nonce. IPv6 addresses share a quota within their /64 subnet.

The entire report request body defaults to 512 KiB; other write requests allow 4 KiB. Only uncompressed JSON is accepted, with a 10-second upload deadline. Submissions allow up to 20 components with no duplicate or unknown keys; Canvas PNG data URLs remain capped at 250,000 characters. The service retains at most 500 reports and 32 MiB of serialized report data. New writes are rejected at capacity; deletion or expiration frees space.

Default per-source limits per minute / per 24 hours: network overview 12 / 300; DNS sessions 10 / 120; DNS result polling 40 / 480; report reads/deletes 30 / 500; comparisons 10 / 100. Quotas use fixed windows and deployment settings can change these defaults. Follow response headers and current service settings. Respect Retry-After on a 429 response and avoid automatic repeated retries.

The current implementation retains submitted component values, including optional Canvas images and audio samples. A report ID allows reading, comparing and deleting a report; share it only as needed. Data lives in one service process for up to 24 hours, is not shared between processes and may be cleared by a restart. Rate counters are also process-local and reset on restart.

Error responses

400: invalid JSON, tier or components. 401: invalid, used or expired session/nonce. 404: missing or expired report. 408: upload timeout. 413: body or Canvas limit exceeded. 415: unsupported media type or compression. 429: rate, quota or concurrency exceeded. 503: storage capacity or network probes unavailable. Rate/capacity rejections include Retry-After. X-RateLimit-Limit, Remaining and Reset describe the quota and reset time. Check HTTP status and do not interpret failures as successful security checks.