npm package: @hienhoceo/n8n-nodes-cloudflare-dns
Description: Comprehensive Cloudflare DNS automation toolkit for n8n
Author: hienhoceo
Latest version: 1.0.8

# n8n Cloudflare DNS Toolkit

Interact with the full Cloudflare DNS API directly inside your n8n workflows: manage records, bulk import/export entire zones, enforce DNSSEC, and run DNS analytics without leaving your automation.

Maintained by **CÔNG TY CỔ PHẦN DPS.MEDIA (DPS MEDIA JSC)**  
56 Nguyen Dinh Chieu, Tan Dinh Ward, District 1, Ho Chi Minh City, Viet Nam  
Email: marketing@dps.media · Phone: +84 961 545 445  
Tax ID: 0318700500 · Vietcombank: 1051160909

---

## Table of Contents
1. [Quick Start](#quick-start)
2. [Getting the Right Cloudflare API Token](#getting-the-right-cloudflare-api-token)
3. [Adding the Credential to n8n](#adding-the-credential-to-n8n)
4. [Using the Cloudflare DNS Node](#using-the-cloudflare-dns-node)
5. [Operation Reference](#operation-reference)
6. [Field Reference](#field-reference)
7. [Troubleshooting](#troubleshooting)
8. [Development](#development)
9. [License](#license)

---

## Quick Start
1. **Install the community node**
   - *n8n UI:* go to *Settings → Community Nodes → Install*, enter `n8n-nodes-cloudflare-dns`.
   - *CLI / project:* `npm install n8n-nodes-cloudflare-dns`.
2. **Create a Cloudflare API token** with the scopes described below.
3. **Create a credential** in n8n named “Cloudflare DNS API” and paste the token.
4. **Add the “Cloudflare DNS” node** (group: Transform) to your workflow and choose the resource/operation you need.
5. **Run the workflow** once to confirm the credential test and API access succeed.

---

## Getting the Right Cloudflare API Token
⚠️ **IMPORTANT**: Account API tokens are no longer accepted. You must create a User API token as described below.

Follow these steps carefully to avoid scope errors inside n8n:

1. Sign in to [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens) (My Profile → API Tokens). Account-level API tokens from the "Account API tokens" menu will **not** work.
2. Click **Create Token** → choose **Custom token**.
3. Under **Permissions** add the rows below (use **Add more** to insert each line):  
   1. `Zone → Zone → Read`  
   2. `Zone → DNS → Edit`  
   3. *(Optional, only if you will run analytics operations)* `Zone → Analytics → Read`
4. Under **Zone Resources** choose **Include → All zones from an account** (recommended).  
   - To restrict the token, change to **Include → Specific zone** and pick the zones you want the node to manage.  
   - Never leave this on **Exclude**; that prevents the node from seeing any zones.
5. Leave **Client IP Address Filtering** empty unless you know the fixed public IP addresses of your n8n instance.  
6. Leave **TTL** blank unless you want the token to expire automatically.  
7. Save the token, copy it immediately, and store it securely—Cloudflare only shows it once.

Tip: if a dropdown inside the node stays empty (e.g. zones or records), double-check that the token really includes `Zone → Zone → Read` for the relevant zone.

---

## Adding the Credential to n8n
⚠️ **IMPORTANT**: Use the User API token you just created. Account API tokens are no longer accepted and will fail credential tests.

1. In n8n open *Credentials* and click **New**.
2. Search for **Cloudflare DNS API** and select it.
3. Paste the API token into the **API Token** field.
4. (Optional) Rename the credential to something meaningful like “Cloudflare DNS – Production”.
5. Click **Test credential** – the node calls `/user/tokens/verify`. A green check means the scopes and zone access are valid. If it fails, double-check the token for missing permissions or stray spaces/newlines.

You only need to configure the credential once; reuse it across multiple nodes and workflows.

---

## Using the Cloudflare DNS Node
1. Drag the **Cloudflare DNS** node into your workflow (category: Transform).
2. Assign the credential you created above.
3. Pick a **Resource**:
   - `DNS Record`
   - `Zone File`
   - `DNSSEC`
   - `DNS Analytics`
4. Pick an **Operation** – the list changes with the selected resource.
5. Fill in the required fields. Most dropdowns (Zone, DNS Record) auto-load from Cloudflare. If a zone doesn’t appear, switch the selector to **Domain Name** and type the root domain (for example `dps.media`), or choose **Zone ID** and paste the 32-character ID manually.
6. Execute the node; responses arrive in JSON (or binary for exports) and can be chained to other n8n nodes.

For multi-item workflows, enable **Continue On Fail** in the node settings if you want the node to process later items even when one fails.

---

## Operation Reference

### DNS Record Operations
| Operation | When to Use | Key Fields |
|-----------|-------------|------------|
| **Create** | Add a brand-new record. | Zone, Type, Name, Content, Additional Fields |
| **Update** | Replace an entire record. | Zone, DNS Record (dropdown), Type, Name, Content, Additional Fields |
| **Patch** | Change only specific attributes. | Zone, DNS Record, Patch Fields (JSON) |
| **Get** | Retrieve a record by ID. | Zone, DNS Record |
| **Get Many** | List records with filtering & pagination. | Zone, Return All / Limit, Filters collection |
| **Delete** | Remove a record. | Zone, DNS Record |
| **Scan** | Ask Cloudflare to scan your zone for DNS records. | Zone |

Supported record types: `A`, `AAAA`, `CAA`, `CNAME`, `DNSKEY`, `DS`, `HTTPS`, `LOC`, `MX`, `NAPTR`, `NS`, `PTR`, `SPF`, `SRV`, `SSHFP`, `SVCB`, `TLSA`, `TXT`, `URI`.

### Zone File Operations
| Operation | Description |
|-----------|-------------|
| **Export** | Downloads the zone in BIND format and stores it as binary data on the item (default property: `data`). |
| **Import** | Uploads a BIND file from a binary property and lets Cloudflare create/update records in bulk. |

### DNSSEC Operations
| Operation | Description |
|-----------|-------------|
| **Get** | Returns DNSSEC status, DS/KEY data, and signature configuration for the zone. |
| **Update** | Toggles DNSSEC (`active`/`disabled`) or inherits the account default. Requires the `Zone → DNSSEC → Edit` right (included in DNS Edit). |

### DNS Analytics Operations
| Operation | Description |
|-----------|-------------|
| **Query** | Executes an analytics query with custom dimensions and metrics; returns raw data rows. |
| **Report** | Generates aggregated data with optional `time_delta`, sorting, and limits. Requires the `Zone → Analytics → Read` scope. |

---

## Field Reference
- **Zone** (`zoneId`): Either pick from the dropdown (populated via `/zones`), switch to *Domain Name* and type the root domain (for example `example.com`) to auto-resolve the ID, or paste the 32-character Zone ID directly. If the list is empty, ensure the token has `Zone → Zone → Read` and that the zone is included under Zone Resources.
- **DNS Record** (`recordId`): Loads records for the selected zone. Use **Get Many** first to discover IDs if needed.
- **Additional Fields**
  - *Data (JSON)*: Paste JSON for complex records (SRV, HTTPS, LOC, etc.). The node validates JSON before sending it to Cloudflare.
  - *Priority*: Enabled for record types that expect it (MX, SRV, URI).
  - *Tags*: Enter a comma-separated list; the node converts it to an array automatically.
- **Patch Fields**: Provide JSON containing only the attributes you want to change. Example:
  ```json
  {
    "ttl": 300,
    "proxied": true
  }
  ```
- **Binary Property** / **Binary Property (Import)**: Name of the binary property on the incoming item. For exports the node writes to this property; for imports the node reads from it.
- **Dimensions / Metrics**: Accept comma-separated values. Common metrics include `queryCount`, `uncachedCount`; dimensions include `queryName`, `queryType`.

---

## Troubleshooting
- **“Failed to load options” for Zone or DNS Record**  
  The API token lacks `Zone → Zone → Read` or the zone is not included under **Zone Resources → Include**. Edit the token to include “All zones from an account” or explicitly select your zone.

- **403 or 9109 errors when editing records**  
  Ensure the token includes `Zone → DNS → Edit` and the zone is covered by the token’s resource scope.

- **Analytics operations return empty data**  
  Add `Zone → Analytics → Read`, generate a new token, paste it into n8n, and re-test.

- **Credential test fails ("Authorization failed")**
  Copy the token again without spaces, make sure it has not expired (TTL) or been deleted, and ensure **Client IP Address Filtering** is empty unless your n8n host matches the allowed IPs. You can also verify the token manually with `curl -H "Authorization: Bearer <token>" https://api.cloudflare.com/client/v4/user/tokens/verify`. ⚠️ **Account-level tokens will fail**—make sure you created the token under *My Profile → API Tokens*.

- **Zone import fails**  
  Confirm the binary data is valid BIND syntax and that the node points to the correct binary property. Cloudflare rejects files containing unsupported directives.

- **Need to operate on multiple zones**  
  Either create one credential with *All zones* permission, or duplicate the node and switch credentials per environment (e.g., staging vs production).

---

## Development
```bash
npm install
npm run lint
npm run build
```
The `prepublishOnly` script runs build and lint to keep TypeScript output and icon assets up to date before publishing.

---

## License
MIT © CÔNG TY CỔ PHẦN DPS.MEDIA