---
title: "Cloudflare setup and permissions · GeoHarness"
description: "Create the Cloudflare API token GeoHarness needs, the exact permission groups per feature, free-plan limits and what happens when access is missing."
canonical: "https://geo.avarok.net/docs/cloudflare/"
tokens: 2010
---

# Cloudflare setup, permissions and limits

GeoHarness needs one Cloudflare API token and your account ID. The token needs only the permission groups of the features you enable, and preflight probes each one before anything is changed.

Updated 2026-11-19 · Source: [cloudflare-permissions.json](https://github.com/Avarok-Cybersecurity/geoharness/blob/main/cloudflare-permissions.json)

## How do I create the API token?

1. In the Cloudflare dashboard open **My Profile → API Tokens** and choose **Create Token → Create Custom Token**.
2. Name it, for example `geoharness-<site>`.
3. Add each permission group in the table below that your target and optimizations need: account groups under **Account**, zone groups under **Zone**.
4. Under **Account Resources** include only your account; under **Zone Resources** include only the zone that serves your domains.
5. Create the token and store it as the repository secret `CLOUDFLARE_API_TOKEN`; store your account ID as `CLOUDFLARE_ACCOUNT_ID`.

## Which permission groups does the token need?

API token permission groups (from cloudflare-permissions.json)

| Permission group           | Scope   | Needed for                                                                                   |
| -------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| Cloudflare Pages Write     | account | `pages-deploy`, `pages-custom-domain`                                                        |
| Workers Scripts Write      | account | `workers-deploy`                                                                             |
| Bot Management Write       | zone    | `bot_fight_mode`, `ai_bots_protection`                                                       |
| DNS Write                  | zone    | `workers-custom-domain`, `pages-custom-domain`                                               |
| Response Compression Write | zone    | `zstd`                                                                                       |
| Workers Routes Write       | zone    | `workers-custom-domain`                                                                      |
| Zone Read                  | zone    | `zone-read`                                                                                  |
| Zone Settings Write        | zone    | `email_obfuscation`, `rocket_loader`, `early_hints`, `http3`, `brotli`, `smart_tiered_cache` |
| Zone Transform Rules Write | zone    | `rewrite-rules`                                                                              |

Per feature, as preflight checks them:

| Feature                 | What it does                                                                   | Groups                                             |
| ----------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------- |
| `workers-deploy`        | Upload the assets-only (or negotiate) Worker                                   | Workers Scripts Write (account)                    |
| `workers-custom-domain` | Attach the site's domains to the Worker as Custom Domains                      | Workers Routes Write (zone), DNS Write (zone)      |
| `pages-deploy`          | Create the Pages project and upload a deployment                               | Cloudflare Pages Write (account)                   |
| `pages-custom-domain`   | Attach domains to the Pages project and create their proxied CNAMEs            | Cloudflare Pages Write (account), DNS Write (zone) |
| `zone-read`             | Find the zone that serves each domain                                          | Zone Read (zone)                                   |
| `rewrite-rules`         | URL Rewrite Transform Rules that serve markdown twins on Accept: text/markdown | Zone Transform Rules Write (zone)                  |
| `email_obfuscation`     | Turn Email Obfuscation off (it rewrites HTML that agents and twins read)       | Zone Settings Write (zone)                         |
| `rocket_loader`         | Turn Rocket Loader off (it rewrites script tags and hurts Lighthouse)          | Zone Settings Write (zone)                         |
| `early_hints`           | Turn Early Hints on                                                            | Zone Settings Write (zone)                         |
| `http3`                 | Turn HTTP/3 on                                                                 | Zone Settings Write (zone)                         |
| `brotli`                | Turn Brotli on                                                                 | Zone Settings Write (zone)                         |
| `smart_tiered_cache`    | Turn Smart Tiered Cache on                                                     | Zone Settings Write (zone)                         |
| `zstd`                  | Compression Rule preferring zstd for the site's host                           | Response Compression Write (zone)                  |
| `bot_fight_mode`        | Turn Bot Fight Mode off so AI crawlers receive HTTP 200                        | Bot Management Write (zone)                        |
| `ai_bots_protection`    | Set AI bots protection to disabled so AI crawlers receive HTTP 200             | Bot Management Write (zone)                        |

Opt out of any zone optimization with `extra-optimizations` (for example `all -zstd`) and its permission is no longer required.

## What are the free-tier limits?

Cloudflare free-plan limits GeoHarness works within

| Resource                      | Free plan                   | GeoHarness use                                                |
| ----------------------------- | --------------------------- | ------------------------------------------------------------- |
| Transform Rules (URL Rewrite) | 10 rules per zone, no regex | 3 rules per host, built from `concat` and `wildcard_replace`  |
| Workers static asset requests | Free and unlimited          | Every page, twin and file is a static asset                   |
| Workers requests              | 100,000 per day             | None, unless the zone is not accessible (fallback below)      |
| `_headers` rules              | 100                         | The site's own rules plus GeoHarness's; more is a build error |
| Markdown for Agents           | Pro plan and above          | Not used; reproduced with twins and rewrite rules             |

## What happens when something is missing?

- **Missing permission:** preflight fails before any change and lists every missing group with the feature that needs it.
- **No zone access:** GeoHarness falls back to a negotiate Worker that runs before the assets. It counts against the 100,000 requests per day of Workers Free; past that Cloudflare answers HTTP 429 (error 1027) until the daily reset. The run warns, and the summary says so.
- **Audit or Lighthouse failure:** the run stops before deploying; the live site keeps the previous build.
- **Edge propagation:** verify polls the live page for this build's `<meta name="build">` every 10 seconds for up to 5 minutes, then fails.
- **Existing rules:** only rules whose description starts with `geoharness:<host>` are created or updated; every other rule in the zone is sent back unchanged.

```json
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "author": {
    "@type": "Organization",
    "name": "Avarok Cybersecurity",
    "sameAs": [
      "https://github.com/Avarok-Cybersecurity"
    ],
    "url": "https://avarok.net"
  },
  "description": "Create the Cloudflare API token GeoHarness needs, the exact permission groups per feature, free-plan limits and what happens when access is missing.",
  "inLanguage": "en",
  "isPartOf": {
    "@type": "WebSite",
    "name": "GeoHarness",
    "url": "https://geo.avarok.net/"
  },
  "name": "Cloudflare setup and permissions · GeoHarness",
  "url": "https://geo.avarok.net/docs/cloudflare/"
}
```
