Cloudflare Integration Workflow

The Cloudflare integration lets you deploy Monocle without changing your application code.

This is the no-code setup path for customers who want to start assessing traffic through Cloudflare. Once configured, Monocle can analyze traffic on selected routes and surface results in the dashboard.

Blocking is only applied when policy-based enforcement is enabled.

How it works

The Cloudflare integration deploys a Cloudflare Worker to the routes you choose.

That worker allows Monocle to assess traffic before it reaches your application.

You can use the integration to:

• Assess traffic without adding code to your site
• Choose which routes Monocle should run on
• Configure a block response
• Redeploy the worker when updates are available
• Remove the worker when it is no longer needed

Before you begin

You need access to:

• A Cloudflare account
• The Cloudflare zone for the domain you want to protect
• Permission to create Cloudflare API tokens
• Permission to deploy Cloudflare Workers

You will also need to create a Cloudflare API token with the required permissions.

Create a Monocle app

To start the Cloudflare integration:

1. Create a new Monocle app.
2. Enter the app name.
3. Choose Cloudflare as the integration type.
4. Continue to the Cloudflare connection step.

Monocle will then ask you to connect your Cloudflare account using an API token.

Create a Cloudflare API token

In Cloudflare, create an API token using the Edit Cloudflare Workers template.

Go to Cloudflare Dashboard → My Profile → API Tokens → Create Token, then select Use template next to Edit Cloudflare Workers.

The token needs permissions that allow Monocle to deploy and manage the Cloudflare Worker for your selected domain.

Required configuration includes:

Use the specific zone for the domain where Monocle will run.

Validate the API token

After creating the token in Cloudflare:

1. Copy the API token.
2. Return to Monocle.
3. Paste the token into the Cloudflare integration setup.
4. Select Validate token.
5. Continue once the token is valid.

If the token is invalid, Monocle will not be able to configure or manage the Cloudflare Worker.

Configure worker routes

Worker routes define where Monocle runs on your site.

You can apply Monocle to:

• All traffic on a domain
• A specific route
• A specific path such as /login
• A protected flow such as checkout or account creation

To apply Monocle to all traffic on a domain, use a wildcard route.

Example:

your-domain.com/*

To apply Monocle only to a login route:

your-domain.com/login*

If you already use Cloudflare Workers, make sure no existing worker uses the same route. Cloudflare does not allow two workers to run on the exact same route.

Configure the block response

The block response controls what users see when traffic is blocked.

You can configure:

• Response body
• Page title
• HTTP status code
• Redirect URL

The default response status is typically 403.

You can also redirect blocked users to a custom block page if you already have one.

Deploy the worker

Once the API token, routes, and block response are configured, select Deploy worker.

After deployment, Monocle will begin testing for traffic on the configured route.

When traffic is detected, the integration status will update to show that Monocle is assessing traffic.

Blocking requires Policy API

The Cloudflare integration can assess traffic without code changes.

However, assessment is not the same as blocking.

By default, Monocle will allow all traffic unless your policy configuration returns a block decision.

To actively block traffic, you must:

1. Have access to policy enforcement.
2. Enable the Policy API.
3. Select a blocking strategy.
4. Configure the policy rules you want to apply.

If your policy is set to Allow All, Cloudflare will continue allowing traffic even if the worker is deployed.

Worker version updates

Monocle may release new versions of the Cloudflare Worker.

When a new worker version is available, the Cloudflare integration page will show that an update is available.

To update the worker, select Redeploy.

You do not need to repeat the full setup flow when redeploying an existing worker.

Updating an API token

If your Cloudflare API token is rotated, revoked, or changed, Monocle may lose permission to manage the worker.

The deployed worker may continue running, but Monocle will not be able to update configuration, remove the worker, or redeploy until a valid token is provided.

If you see an invalid token warning:

1. Create or copy a valid Cloudflare API token.
2. Update the token in Monocle.
3. Validate the token again.

Removing the worker

You can remove the Cloudflare Worker from Monocle.

Removing the worker stops Monocle from assessing traffic on the configured Cloudflare routes.

If you redeploy the worker later, you may need to add worker routes again before traffic is intercepted.

Troubleshooting

Traffic is not being assessed

Check that:

• The worker is deployed.
• At least one route is configured.
• The route matches the traffic you are testing.
• No existing Cloudflare Worker is using the same route.
• Traffic is reaching the configured domain and path.

The API token is invalid

Check that:

• The token has the required Worker permissions.
• The token includes the correct Cloudflare account.
• The token includes the correct zone / domain.
• The token has not been rotated or revoked.

The worker is deployed but not blocking traffic

Check your policy configuration.

The Cloudflare worker only blocks traffic when Monocle returns a block decision.

If your policy is set to Allow All, or if Policy API enforcement is not enabled, traffic will continue to be allowed.

A route conflict appears

A route conflict means another Cloudflare Worker is already using the same route.

Use a different route, remove the existing worker route, or adjust the path so the Monocle worker does not overlap with another worker.

Manual setup with Wrangler

If you prefer to configure and deploy the Cloudflare Worker manually using the Wrangler CLI, follow the steps below.

1. 1

   Install and authenticate the Cloudflare wrangler utility

   Run the following to install globally via npm and login:

   terminal

   Copy code

   npm install -g wrangler
   wrangler login

2. 2

   Pull and install the monocle-cloudflare-plugin repository

   Clone the monocle cloudflare plugin to your local workspace and install dependencies.

   Note: This local setup will house your configuration. It is recommended that you manage this with your own version control or fork monocle to easily pull future updates from Spur.

   terminal

   Copy code

   git clone https://github.com/spurintel/monocle-plugin-cloudflare
   cd monocle-plugin-cloudflare
   npm install

3. 3

   Configure the worker

   In your local repository, you will need to modify the wrangler.toml file for your site and Cloudflare account.

   1. Open the wrangler.toml file in your text editor.
   2. Copy the example settings here or modify the existing file.
   3. Save and close.

   Note: Ensure that you set the compatibility_date (today), account_id, zone_id, and route.

   toml

   Copy code

   name = "monocle"                # Name of your worker
   main = "index-spur-managed.js"  # Do not change - this is the entry point for the worker
   compatibility_date = "2025-02-27"
   account_id = "YOUR_ACCOUNT_ID"
   workers_dev = false             # Set to false to deploy to custom domain
   route = { pattern = "*YOUR_DOMAIN_HERE/path/to/protect/*", zone_id = "YOUR_ZONE_ID" }

4. 4

   Configure monocle variables

   Return to your terminal and run the following commands to store your App's publishable key and secret key. You will be prompted to provide the values for each. You can copy the values from the Monocle Dashboard and paste them into the terminal when prompted.

   terminal

   Copy code

   wrangler secret put SECRET_KEY
   wrangler secret put PUBLISHABLE_KEY
   # This is a unique auto-generated cookie secret.
   # If you prefer, create a new one: "openssl rand -hex 32"
   wrangler secret put COOKIE_SECRET_VALUE

5. 5

   Deploy the worker

   Run the following command to deploy your cloudflare worker to protect your configured routes:

   terminal

   Copy code

   wrangler deploy

Session-Level Analysis (Optional)

1. 6

   Session-level analysis

   Session-level decryption for Cloudflare Workers is configured through the monocle plugin. Refer to the monocle cloudflare plugin documentation for form enrichment and server-side decryption setup.

Related

• Policies
• Blocking / Enforcement
• Monocle Assessment — Understand the decrypted assessment payload
• Assessment Decryption — Decryption API and backend decryption options