# Connect Cloudflare

Canonical URL: https://docs.fuse.init.inc/integrations/cloudflare/setup

Create a zone-scoped Cloudflare API token and submit it with the zone id to Init.



## Before you start [#before-you-start]

Cloudflare uses **customer bearer credentials**. Init binds one API token to **one zone**. There is no Init platform OAuth app and no generic HTTP proxy for Cloudflare hosts.

**Connection admin/user** creates a zone-scoped API token in Cloudflare and submits the token plus the zone id.

You need:

* Permission to create API tokens in the Cloudflare account that owns the zone.
* The target **zone id** (32-character hex) from the Cloudflare dashboard or API.
* A dedicated non-production zone for mutation testing; never point write validation at production DNS.

## Configure the provider [#configure-the-provider]

### Create a zone-scoped API token (**Connection admin/user**) [#create-a-zone-scoped-api-token-connection-adminuser]

1. In Cloudflare, open **My Profile → API Tokens** (or **Manage Account → Account API Tokens** for account-owned tokens).
2. Create a custom token with least privilege for the single zone you will connect:
   * **Zone → Zone → Read** on that zone.
   * **Zone → DNS → Edit** when callers need create/update/delete; use **DNS → Read** only for read-only connections.
3. Restrict the token’s **Zone Resources** to the one zone Init will bind. Do not grant account-wide DNS Edit.
4. Copy the token once. Prefer prefixed formats (`cfut_` / `cfat_`) when Cloudflare issues them.
5. Copy the zone id from the zone overview (32 hex characters).

Do **not** use the Global API Key with account email. Init rejects `api_key` + `email` Connect shapes.

There is no custom API origin to configure. Init always calls `https://api.cloudflare.com/client/v4`.

## Connect to Init [#connect-to-init]

**Connection admin/user** starts a Cloudflare Connect session and submits:

| Field          | Required | Notes                                                                      |
| -------------- | -------- | -------------------------------------------------------------------------- |
| `access_token` | Yes      | Cloudflare API token with Zone Read (and DNS Edit when writes are needed). |
| `zone_id`      | Yes      | 32-character hex zone id. One connection = one zone.                       |

Use `cfut_example-token-not-valid` only as an inert documentation placeholder. Never paste a live token into docs.

Init stores the token in Vault and persists only account/zone metadata and the fixed API origin outside Vault.

## Permissions [#permissions]

| Capability         | Cloudflare permission | Init actions                                                     |
| ------------------ | --------------------- | ---------------------------------------------------------------- |
| Read zone metadata | Zone Read             | `zone.get`                                                       |
| Read DNS           | DNS Read              | `dns_records.list`, `dns_records.get`                            |
| Write DNS          | DNS Write (Edit)      | `dns_records.create`, `dns_records.update`, `dns_records.delete` |

Writes support **A**, **AAAA**, **CNAME**, **TXT**, and **MX** only. Updates are full `PUT` replacements—read the record first so concurrent edits are not overwritten. Create/update/delete are not exposed over MCP.

Init does **not** offer a generic proxy to `api.cloudflare.com`. Callers use the typed actions only.

## Verify the connection [#verify-the-connection]

1. Complete Connect and confirm the connection is active.
2. Run Init’s connection test (zone get plus a DNS list probe) or a safe read such as `zone.get`.
3. Success looks like Cloudflare accepting the bearer token for the bound zone without `401`/`403`, with the connection showing the zone name and account metadata.

Connection testing proves DNS **read**. DNS write requires a token with DNS Edit and should be validated only against a dedicated test zone.

## Rotate or revoke access [#rotate-or-revoke-access]

1. Create a new zone-scoped token with the same least-privilege permissions (Cloudflare supports overlap rotation via roll token).
2. Reconnect in Init with the new `access_token` and the same `zone_id`.
3. Revoke or roll the previous token in Cloudflare.

If a token is exposed, revoke it immediately, then reconnect.

## Troubleshooting [#troubleshooting]

| Symptom                    | What to check                                                               |
| -------------------------- | --------------------------------------------------------------------------- |
| `401` Unauthorized         | Token revoked, mistyped, or wrong token type.                               |
| `403` Forbidden            | Token lacks Zone Read / DNS Read / DNS Write for the bound zone.            |
| Zone binding failure       | `zone_id` is wrong or the token cannot read that zone.                      |
| Write rejected             | Token is read-only, or record type is outside A/AAAA/CNAME/TXT/MX.          |
| Update wiped fields        | `dns_records.update` is a full PUT; include every field you intend to keep. |
| Proxy / custom host errors | Cloudflare has no generic proxy allowlist; use typed actions only.          |