Post-signup usage
Report billable activity from your backend to detect shared or resold free accounts. Usage events do not consume your verification quota.
POST /v1/usage
{ "secret": "sk_…", "events": [{ "accountId": "user_123", "units": 1, "ip": "198.51.100.7", "userAgent": "Mozilla/5.0 …", "ts": 1792713600000, "quota": 100 }] }
{ "accepted": 1, "flagged": [{ "accountId": "user_123", "reasons": ["fast_burn"] }] }Send up to 500 events per request and 120 requests per site per minute. accountId is required (1–256 characters). units defaults to 1 and must be finite and nonnegative. ts is optional: use Unix milliseconds as a nonnegative safe integer. Omit it to use server time. quota is optional and must be a positive finite number. ip and userAgent are optional strings. Empty batches are accepted. Invalid fields return 400; invalid secrets return 401.
Detectors
| Reason | Threshold |
|---|---|
| account_networks | More than 10 distinct network prefixes on one account in a UTC hour. |
| account_pool | One network prefix on more than 5 distinct accounts in a UTC hour. |
| ua_spread | More than 5 UA families across the last 24 hourly buckets. |
| fast_burn | Units at least 90% of the supplied quota during the first 24 hours after the account's first verify. |
Flagged accounts appear in the dashboard Usage tab. Their last verified browser/fingerprint keys receive a 30-day usage report. A later verify sharing those keys gets linked_usage_abuse and is limited in block mode. Observe mode reports the would-be decision. Legit feedback still overrides. Clear withdraws the account flag and its usage reports, but leaves fraud or legit labels unchanged. Further abusive activity can flag the account again.
Privacy and retention
The endpoint stores only hourly requests, units, keyed per-site network-prefix hashes (up to 64 per account/hour), and parsed UA family names (up to 16). It never stores raw IPs or user agents. Aggregates expire after 30 days. No network-prefix key is marked as a device report. Opted-in sites may contribute existing verify network keys to the shared network.
Testing
Use any documented test secret, such as test-allow-secret. Events are accepted but not stored. Only account IDs beginning with flag_ are returned as flagged, with reason test.
Dashboard API
Authenticated owners can GET /api/sites/:key/usage for {flags:[{accountHash,accountId,reasons,units24h,networks,lastFlagged}]}. POST /api/sites/:key/usage/:accountHash/clear to withdraw a flag. The demo is read-only.