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

If your CDN or edge already terminates TLS and runs a bot challenge, 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. Forwarding is optional. The Beacon and Pixel work the same without it.

Prerequisites

A project-scoped API key for the proxy. The kya-os CLI creates one with the proxy purpose, which carries only the forward permission. It can authenticate forwarded evidence and nothing else, so a key on your edge can't read or change anything in the project. A key with write permission also works. See Credentials.
An edge that can proxy a path to another origin and set request headers on the proxied request.

Keep the key in your edge configuration. It never reaches the browser.

What Checkpoint does with forwarded headers

Header	What Checkpoint does with it
`KYA-Forwarded-IP`	Uses the visitor's address instead of your CDN's for rate limiting and storage.
`KYA-Forwarded-JA4`	Scores it as the request's TLS fingerprint, so a browser User-Agent sent from a known non-browser TLS client is flagged.
`KYA-Forwarded-Challenge-Id`	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 shared. These thresholds are fixed and apply to every project.

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

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, X-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"

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, such as the challenge outcome when a challenge ran, a visitor can send that header themselves and it reaches Checkpoint next to your key.

Checkpoint ignores an optional value in the wrong format and still accepts the request. The JA4 source depends on your edge:

Edge	Where the JA4 lives
CloudFront	The `CloudFront-Viewer-JA4-Fingerprint` header
Cloudflare Workers	`request.cf.botManagement.ja4`, on zones with Bot Management

Responses

A forwarded request that's accepted gets the same response as a direct one. If X-API-Key is present but unusable, 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 none of `forward`, `write` or `admin`
`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.

How keys are checked

The ingest edge checks each key against a copy it keeps for a short time. It asks Checkpoint about once a minute per key, and sends a hash of the key, never the key.

Situation	What happens
Key revoked or expired	The change takes up to 60 seconds to reach the ingest edge. Until the cached answer expires, the key keeps forwarding.
Key refused	Remembered for 30 seconds. A key you've just created is accepted on its next request after that window.
Checkpoint unreachable during a key check	Traffic is still accepted. The batch is queued, and its forwarded evidence is checked again when the queue replays it.
Key fails the check on replay	The batch is kept and scored with the connecting address. The detection records that forwarding was discarded.
Outage, key validated in the last 24 hours	Still counted against the forwarded IP, so a busy proxy isn't throttled. A key revoked during the outage keeps that treatment until Checkpoint is reachable again.
Outage, key not validated recently	Counted against the connecting address. A proxy sending more than about 200 requests per second from one address can see `429` responses until Checkpoint returns.

Rate limits follow the visitor. A valid key is counted against the forwarded IP, so visitors behind one proxy don't share a budget. An unknown, refused, or not-yet-validated key is counted against the connecting address.

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.

Turn forwarding off

Stop setting X-API-Key and the KYA-Forwarded-* headers. Checkpoint then treats the request as a direct one.

Forward edge evidence