Connect Cloudflare | Contentstack Canoe

Enterprise feature

Agent traffic is part of the Enterprise plan. To turn it on for your workspace, talk to us.

What the Worker does

People pass straight through. Their requests go to your origin untouched. When someone arrives from a link in an AI answer, the page and the assistant are counted, with no IP address, user agent or cookies.
AI agent visits are reported. Agents get your normal page. After the response is on its way, the Worker sends Contentstack Canoe a short record: the time, host and path (without the query string), the agent's user agent and signature headers, how your site answered, and where the request came from: Cloudflare data center, network and country, plus city and region for agent requests only. When Cloudflare marks a request as a verified bot, or your zone has Bot Management, those signals are sent too.
Private data stays private. Cookies, request bodies and form data are never read or sent. The IP address is used to check the agent, and only its network prefix is stored. The Worker sets no cookies and keeps Workers Logs off.
It fails open. If the Worker hits an error, or Contentstack Canoe is slow or down, the request goes to your origin as usual.
Pages stay the same. AI agents get a different version only if you turn on agent-ready pages. They're off by default.

Before you start

Your site on a Cloudflare zone, with the DNS record for each host proxied (orange cloud). Not on Cloudflare? Use Custom edge.
Workers on your Cloudflare plan. The Worker runs on every request to the hosts you pick, people included, so each request counts toward your Workers usage. A paid Workers plan has no daily request limit.
Someone who can create API tokens in that Cloudflare account. The Token step has Copy steps for your admin.
Owner or admin in Contentstack Canoe to connect, change or disconnect. Everyone in the workspace can see the install.

Create the API token

Recommended for enterprise accounts

Install with an account-owned token and a short expiry, such as one day.
Right after install, select Switch to a maintenance token on the Cloudflare card. That token reaches only the installed contentstack-canoe- Worker, plus the zone permissions.
Delete the install token in Cloudflare.

The install token is account-scoped: creating a Worker needs Developer Platform > Workers > Admin, which covers every Worker in the account. Cloudflare only lets a token be limited to one Worker once that Worker exists, which is why the maintenance token comes second.

Three permissions are required. The optional ones each turn on one extra view, and leaving one out only hides that view.

Required permissions

Required token permissions and why each one is needed
Permission	Why	Needed
Developer Platform > Workers > Admin	Create, update and remove the Contentstack Canoe Worker. Editor can't create or remove a Worker. It covers every Worker in the account, but Contentstack Canoe only changes the one it tagged as its own.	Required
Zone > Workers Routes > Edit	Add and remove the routes that run the Worker on your hosts.	Required
Zone > Zone > Read	Find the zone and account that serve your site.	Required

Optional permissions

Optional token permissions and what each one turns on
Permission	What it turns on	Needed
Account > Account Analytics > Read	Before you install: the AI crawlers Cloudflare saw on your site in the last 7 days, and how much traffic the Worker would run on.	Optional
Zone > Analytics > Read	How many AI agent requests Cloudflare blocked or challenged before they reached your site.	Optional
Zone > Bot Management > Read	Your Cloudflare AI crawler setting (allow, block or charge) next to each agent.	Optional
Zone > Zone Settings > Read	Whether Cloudflare already serves markdown to agents for your zone, so it isn't done twice, and whether pay per crawl is on.	Optional

On the Token step, select Create token in Cloudflare. Cloudflare's form opens with the name Contentstack Canoe (your domain), the required zone permissions and most optional ones picked. Remove any optional permission you don't want.
Add Developer Platform > Workers > Admin yourself. Cloudflare's link can't pick it. If your form doesn't offer it, add the legacy Account > Workers Scripts > Edit instead. Add Zone > Bot Management > Read the same way if you want it.
Under Zone Resources, pick only your site's zone.
Select Create Token and copy it. Cloudflare shows it only once.

Use an account token, the default. It keeps working when the person who made it leaves.
Set a short expiry if you'll switch to a maintenance token. Contentstack Canoe warns you two weeks before any token ends.

Contentstack Canoe encrypts the token and uses it only to install, check, update and remove its Worker.

Connect

Open your brand's settings, select Integrations, then Connect on the Cloudflare card. Four steps follow: Token, Hostnames, Review and Verify.

Token. Create the token from the link on this step, paste it and select Check token. Token tips and why each permission explains each one and has Copy steps for your admin.
Hostnames. Check the zone and the hostnames to watch, such as brightkeel.example and www.brightkeel.example. Each one gets a Worker route, like www.brightkeel.example/*. To try it on staging first, add only the staging hostname now and the rest later.
Review. The list shows every change Contentstack Canoe will make. Nothing changes until you select Install in observe-only.
Verify. The first test request usually arrives in under a minute, and the page says Cloudflare is connected.

Connect Cloudflare, step 1 of 4: the permissions the token needs, Create token in Cloudflare, Token tips and why each permission, and the field to paste the token. — Step 1 lists the exact permissions, required and optional.

Step 2: the Brightkeel account, the zone brightkeel.example and the hostnames brightkeel.example and www.brightkeel.example, with the two Worker routes to add. — Step 2 for a fictional brand: one route per hostname.

Step 3, Review what will change: upload the Worker, add two routes and send a signed test request, then Install in observe-only. — Step 3. The install starts in observe-only: it reports visits and changes nothing visitors get.

See AI crawlers first. With Account Analytics Read, Show AI crawler visits on the Hostnames step lists the AI crawlers Cloudflare logged on your site in the last 7 days, including ones your security rules blocked.
Agent-ready pages stay off until you turn them on in Agent Traffic.

If your hosts already run a Worker

The review says Needs your consent. If you agree, the Contentstack Canoe Worker runs first and passes every request on to your Worker unchanged. In this setup it reports visits only and doesn't serve agent-ready pages. Every host must run that same Worker.

What changes in Cloudflare

Only what the review lists. DNS, caching, security rules and your other Workers are not touched.

Worker: contentstack-canoe- plus 8 characters, tagged as Contentstack Canoe's own.
Routes: One per host, like www.brightkeel.example/*. With your consent, your existing route points to the Contentstack Canoe Worker instead.
Test requests: A few to your home page after install, then one with each health check, about once an hour. They use the user agent ContentstackCanoeEdgeCheck, not an AI agent's, so AI bot rules don't block them.

Check the install

The Cloudflare card in Integrations shows what's installed and a row for each check: API token, Worker, Routes, Test request and Worker version. They run about once an hour, and Check now runs them right away.

The Cloudflare details on the card: install, account, Worker, routes and version, then checks for the API token, Worker, routes, test request and Worker version, all passing. — A healthy install on a fictional site.

If your zone has Cloudflare Bot Management, the card says so. Verification then uses Cloudflare's own verdict, and those visits show as Verified by Cloudflare in Agent Traffic.

To see a visit yourself, request a page with an AI agent's user agent:

curl -A "Mozilla/5.0 (compatible; GPTBot/1.3; +https://openai.com/gptbot)" https://www.brightkeel.example/pricing

It shows in Agent Traffic within a few minutes, marked Spoofed or Unverified because it doesn't come from OpenAI's network. That's expected. A normal browser visit doesn't show at all.

Update Worker

When a new version is out, the Worker version row says Update available. Update Worker uploads it with the same settings and secret. Nothing else changes.

Turn on optional features later

The Optional features section of the Cloudflare card shows which ones are on. For one that's off, How to turn it on gives the exact steps. Nothing needs to be reinstalled.

In Cloudflare, open the token: Manage Account > Account API Tokens for an account token, or My Profile > API Tokens for a personal one. Select Edit.
Add the permission and save. Account > Account Analytics > Read applies to the account; the Zone permissions apply to your site's zone. The token value stays the same, so there's nothing to paste.
In Contentstack Canoe, select Check again under Optional features on the Cloudflare card.

Optional features on the Cloudflare card: Blocked by Cloudflare on, AI Crawl Control status needing Zone > Bot Management > Read with the steps to add it, Markdown for Agents check on, and Check again. — One feature off, with its steps open.

In Agent Traffic, Turn on more Cloudflare insights takes you to this section.

Use a maintenance token

Recommended. The maintenance token is the least-privilege setup: it can update and remove only the Contentstack Canoe Worker. Under API token on the Cloudflare card, select Switch to a maintenance token. The card lists the steps with your Worker's name.

Create the maintenance token

In Cloudflare, open Manage Account > Account API Tokens and select Create Token.
Name it Contentstack Canoe maintenance (your domain).
Under Permission policies, set the scope to Specified Workers and pick your contentstack-canoe- Worker. Under Individual Workers, choose Admin. Editor can't remove the Worker later.
Add Zone > Workers Routes > Edit for your zone.
Paste the token, confirm you chose Admin and select Check and switch.

Contentstack Canoe checks that the token can manage only this Worker, without changing anything your visitors see. Then delete the install token in Cloudflare. Add any optional permissions you use to this token too. Not available yet when Contentstack Canoe runs in front of your own Worker.

Rotate the secret

The Worker signs its reports with a secret. Rotate secret makes a new one and writes it to your Worker. The old one keeps working for 48 hours, so no visits are lost. If it leaked, tick Stop accepting the old secret right away.

Replace the token

Token expiring, revoked or too broad? Select Replace token and paste one with the same permissions. Contentstack Canoe checks it can reach the Worker before it swaps. The Worker isn't changed. Then delete the old token in Cloudflare.

Remove the Worker

Disconnect on the Cloudflare card lists what it removes before you confirm: the Worker, its routes and the stored token. A route that passed requests on to your own Worker points back to it. Agent traffic already collected stays in your reports. Then delete the token in Cloudflare.

If Cloudflare can't be reached or the token was revoked, the install moves to Needs cleanup at the top of Integrations with the exact steps left. Select Try again with a new token, which is used once and never stored. Or do the steps in Cloudflare and select I removed it. Until then the Worker keeps passing requests through, and Contentstack Canoe ignores what it sends.

Troubleshooting

While you connect

“Cloudflare did not accept this token.”

Fix: copy the whole token again, the value and not its name. If it expired, was disabled or was deleted, create a new one.

“This token is missing a permission Contentstack Canoe needs”

Fix: the message names it. Add it to the token in Cloudflare, then try again.

“Cloudflare did not let this token look up its account.”

Fix: add Account > Account Settings > Read to the token in Cloudflare. It applies to the account, not the zone. Then try again.

“No Cloudflare zone this token can read serves …”

Fix: give the token Zone > Zone > Read and check its Zone Resources include your site's zone.

“The zone … is paused in Cloudflare”

Fix: Workers don't run on a paused or unfinished zone. Resume it, or finish setting it up, in Cloudflare.

“This site is already monitored by another brand”

Fix: disconnect Cloudflare from that brand first. If it's in another workspace, ask an owner there or contact support.

“This site still runs …, a Contentstack Canoe Worker left from an earlier connection”

Fix: finish the steps under Needs cleanup, then review the plan again.

“Your Cloudflare setup changed since you reviewed the plan.”

Fix: select Review again.

“This Cloudflare account has reached its Workers limit.”

Fix: delete a Worker you no longer use, or raise the limit with Cloudflare.

“Cloudflare is limiting requests from this token right now.”

Fix: wait a few minutes, then try again.

After install

“Still waiting for the test request”

Fix: in Cloudflare, check that:

each host's DNS record is proxied (orange cloud)
no more specific route or other Worker takes the request first
WAF, Bot Fight Mode or AI traffic rules don't block it

“Contentstack Canoe can no longer reach your Cloudflare account.”

Fix: the token was revoked or expired. The Worker still runs. Replace the token.

“The Contentstack Canoe Worker is missing from your Cloudflare account.”

Fix: disconnect Cloudflare and connect it again. The same fix works when a route was removed, or when your own Worker behind it is gone.

Fewer AI agent visits than the preview showed

Likely cause: WAF rules, Bot Fight Mode and AI Crawl Control stop some agents before any Worker runs. The preview counts those as blocked or challenged.