Proxy the Beacon or Pixel through your CDN and forward the visitor IP, TLS fingerprint, and bot-challenge result your edge already has

Overview

If your CDN or edge already terminates TLS and runs a bot challenge, you can send the Beacon and Pixel requests through it. Your edge adds what it observed as request headers, and Checkpoint scores the request with them. Nothing new runs in the browser, and there is no token to mint or rotate.

With forwarding in place, Checkpoint:

Uses the forwarded visitor IP for rate limiting, session lookback, and storage, instead of your CDN's address.
Scores the forwarded JA4 as the request's TLS fingerprint, so a browser User-Agent sent from a known non-browser TLS client is flagged.
Counts the TLS stacks and networks that present each challenge clearance. A clearance seen from a second TCP cipher list, or from more than eight networks within 24 hours, is treated as shared.

A shared clearance marks the detection as failing client integrity. Checkpoint stores the detection instead of rejecting it, and the detection reads back with the detection/client-integrity-failure reason code.

Forwarding is optional. The Beacon and Pixel work the same without it, and a request that does not come through a proxy is handled exactly as before.

Prerequisites

A project-scoped API key with write permission. See Credentials. The key stays in your edge configuration and never reaches the browser.
An edge that can proxy a path to another origin and set request headers on the proxied request.

1. Proxy the ingest path

Route a path on your own domain to Checkpoint:

Your path	Proxies to
`/kya/beacon`	`https://kya.vouched.id/api/v1/beacon`
`/kya/pixel`	`https://kya.vouched.id/api/v1/pixel`

Forward the method and body unchanged, along with Content-Type, Content-Encoding (the Beacon gzips batches), User-Agent, and Origin. Then point the clients at your path:

// Beacon
new CheckpointBeacon({ projectId, endpoint: 'https://www.example.com/kya/beacon' });

<!-- Pixel: add to the script tag -->
data-api-endpoint="https://www.example.com/kya/pixel"

2. Add the forwarded headers

Checkpoint treats a request as proxied when it carries X-API-Key together with at least one KYA-Forwarded-* header. A request with neither, or with a key alone, is handled exactly as before.

On every proxied request, first remove any X-API-Key and KYA-Forwarded-* headers the visitor sent, then set these:

Header	Required	Value
`X-API-Key`	Yes	Your project API key
`KYA-Forwarded-IP`	Yes	The visitor's IP address as your edge saw it
`KYA-Forwarded-JA4`	No	The visitor's JA4 TLS fingerprint, for example `t13d1516h2_8daaf6152771_02713d6af862`
`KYA-Forwarded-Challenge`	No	Your challenge outcome for this visitor: `pass`, `fail`, or `none`. Stored on the detection for audit, not scored.
`KYA-Forwarded-Challenge-Id`	No	A hash (hex or base64, 16 to 256 characters) of the visitor's challenge clearance cookie, never the cookie itself

Strip, then set, on every request. If your edge sets a header only when it has a value (for example, the challenge outcome only when a challenge ran), a visitor can send that header themselves and it reaches Checkpoint alongside your key.

Checkpoint ignores an optional value in the wrong format and still accepts the request. The JA4 source depends on your edge. For example, CloudFront sends it in the CloudFront-Viewer-JA4-Fingerprint header, and Cloudflare Workers expose it as request.cf.botManagement.ja4 on zones with Bot Management.

Responses

A forwarded request that is accepted gets the same response as a direct one. If X-API-Key is present but cannot be used, both endpoints answer 401 before scoring or storing anything:

Reason	Cause
`invalid_key`	The key is unknown, revoked, or expired
`unscoped_key`	The key is not attached to a project
`read_only_key`	The key has neither `write` nor `admin` permission
`key_not_for_project`	The key belongs to a different project than the request
`missing_ip`	`KYA-Forwarded-IP` is missing or is not an IP address

The Beacon returns { "success": false, "error": "Forwarding rejected: <reason>" }. The Pixel returns AUTH_INVALID_API_KEY in its error envelope with the same message.

Limits

Checkpoint still derives geography from the connecting address. That address is your CDN's point of presence, which is usually near the visitor but not always in the same city.
The thresholds (one TCP cipher list, eight networks, 24 hours) are fixed and apply to every project.

Forward edge evidence