# Connect Cloudflare

> Watch Cloudflare Pages deployments, Worker errors and your zones. A failed build reaches your Mac's notch with its failing step, and the alert shows the end of the build log.

Source: https://coisland.app/docs/connect-cloudflare/

## What you need

- **You need:** Custom API token, Read only, from My Profile › API Tokens (https://dash.cloudflare.com/profile/api-tokens)
- **The form asks:** Connector name, API token
- **You can watch:** Failed Pages deployments, Worker errors, Zone problems
- **Access:** GET requests and GraphQL analytics queries only, with a token of Read permissions

CoIsland calls Cloudflare's API straight from your Mac: there is no CoIsland server and no CoIsland account. The token stays in your login Keychain. Every request is a `GET`, except Worker errors, which are read with a query to the GraphQL Analytics API.

## Create a Cloudflare API token

Use an API token, never the Global API Key.

1. In the dashboard, open **My Profile › API Tokens** (`dash.cloudflare.com/profile/api-tokens`) and click **Create Token**, then **Create Custom Token**.
2. **Permissions**, all **Read**, for what you will watch:

| Monitor | Permission |
|---|---|
| Failed Pages deployments | Account › Cloudflare Pages › Read |
| Worker errors | Account › Account Analytics › Read (Account › Workers Scripts › Read fills the Worker picker) |
| Zone problems | Zone › Zone › Read |

3. **Account Resources** and **Zone Resources:** the account and zones to watch.
4. Optionally an IP filter and a TTL, then **Continue to summary** and **Create Token**. Copy it: Cloudflare shows it only once.

Any member can create a user API token, but not one that exceeds their role: a read-only role gives a read-only token, and a role without Pages cannot read Pages. On Enterprise, a Super Administrator can turn off API access for the account or for you. Account API tokens need a Super Administrator to create, so CoIsland asks for your own.

## Connect Cloudflare in CoIsland

| Field | What to enter |
|---|---|
| Connector name | What monitors call it. CoIsland suggests `cloudflare` |
| API token | The token you copied |

**Test connector** calls `GET /client/v4/user/tokens/verify` and `GET /client/v4/accounts`, and shows that the token is active, its expiry and the accounts it reads.

## Watch Cloudflare: the three monitor kinds

| Kind | What alerts | What CoIsland calls |
|---|---|---|
| Failed Pages deployments | A deployment of the last 7 days whose latest stage failed | `GET /accounts/{account}/pages/projects/{project}/deployments`, the latest 25 per project |
| Worker errors | A Worker with at least the errors you set (1 unless you choose) in the window (15 minutes unless you choose, from 5 minutes to 24 hours) | `POST /client/v4/graphql`, `workersInvocationsAdaptive` summed by script |
| Zone problems | A zone paused, pending its nameservers, moved or deactivated | `GET /client/v4/zones`, 50 a page |

```text
account:023e105f4ecef8ad9ca31a8372d0c353 project:web env:production branch:main
account:023e105f4ecef8ad9ca31a8372d0c353 script:api errors:50 window:1h
account:all
```

- `account:` is the account's ID, as the pickers fill it; `account:all` watches every zone the token reads.
- A Worker alerts when it starts throwing errors, and again after a quiet window.
- A retried deployment is a new one; a fixed zone leaves the result.

Clicking a row in the notch opens the alert in CoIsland: a failed deployment with its failing stage, every stage, branch, commit and the last 100 lines of its build log; a Worker with its errors and requests in the window; a zone with its status, its nameservers while pending, or "Active" once fixed. **Open in Cloudflare** goes to the deployment, the Workers list or the zone.

A Cloudflare monitor's `-- kind:` is `cloudflare.pages`, `cloudflare.workers` or `cloudflare.zones`.

## Troubleshooting Cloudflare connector errors

- **"The API token was refused."** Cloudflare answered code 1000 "Invalid API Token", 9109 "Invalid access token" or 6003 "Invalid request headers": the token is wrong, expired or disabled, or it is the Global API Key.
- **"Pages project web (needs Cloudflare Pages: Read): not allowed."** The token lacks the permission, or your role does not include it.
- **"Workers analytics (needs Account Analytics: Read): not allowed."** The analytics query was refused for that account.
- **"Rate limited."** Cloudflare allows 1,200 requests every 5 minutes per user, and about 300 analytics queries every 5 minutes; CoIsland waits, then retries.

## Frequently asked questions

### Why not the Workers logs?

Worker errors come from Workers Analytics, which counts every Worker's errors without turning on logs. Reading exception messages needs Workers Observability, whose query API asks for a write permission; CoIsland does not ask for one.