Cloudflare

This guide is for teams already running on Cloudflare who want to add KYA token-based access control to their existing delivery stack. It uses a Cloudflare Workers function, a serverless function that runs at Cloudflare's edge before a request reaches your origin. A Worker validates the incoming kya token on each request and blocks traffic that doesn't present a valid one. For what a kya token is and why validation works this way, see How it works in Enforce KYA-Based Access Control.

Before you start: you'll need a Cloudflare account with Workers enabled, and your website or API already served through Cloudflare. A reference implementation is available in the skyfire-solutions-cloudflare-news-crawler-demo repo.

Identify your setup

Two questions determine which setup below applies to you.

Together, these answers point you to one of four setups below: CDN or API Gateway, each with either bot filtering or blanket enforcement.

Follow the matching setup

Select the tab below that matches your product, then the sub-tab that matches which traffic should require a token.

Use this if your website is served through Cloudflare's CDN.

1. Create and configure your Worker

1. Create a Worker.
2. Install the packages the Worker code needs:
   Bash

   npm install validator jose @cloudflare/workers-types

3. In wrangler.jsonc, set these environment variables under vars. They tell the Worker which Skyfire environment to validate tokens against:
   JSON

   "vars": {
     "BACKEND_API_URL": "https://api.skyfire.xyz",
     "OFFICIAL_SKYFIRE_JWT_ALGORITHM": "ES256",
     "OFFICIAL_SKYFIRE_JWT_ISSUER": "https://app.skyfire.xyz"
   }

2. Choose which traffic requires a token, and deploy

This path adds a Cloudflare WAF rule, a request-filtering rule that runs at Cloudflare's edge, so tokens are only required from bots. Human visitors pass through unchecked.

1. Start from this path's example Worker code, which validates the kya token. Adapt it to your needs, then deploy it.
2. In the Cloudflare Dashboard, go to Security → Security rules.
3. Create a custom rule that checks for bot-likeliness (Cloudflare's Bot Score) plus the presence of a kyapay-token (and deprecated skyfire-pay-id) header, and blocks the request on this hostname otherwise.

Example rule from our live demo:

3. Connect your Worker to your website

With your Worker deployed, add a route: open it in the Cloudflare Dashboard, go to Domains, and add a route to your CDN-hosted website under Custom Domains & Routes.

What to return when blocking a request

When your Worker blocks a request, return a clear error that tells the caller how to get a token. Use these responses:

For the full set of recommended responses, including plain-text versus structured JSON for LLM callers, see Handling Missing or Invalid Tokens.

Demo

References

• Verify and Extract Data from Tokens
• Handling Missing or Invalid Tokens
• Cloudflare Workers docs
• Wrangler docs
• Cloudflare Bot Score