Skip to content

Cloudflare Setup

Dreadnought needs two things from Cloudflare: an API token (to make changes on your behalf) and the Zone ID for each domain you want to manage. This guide walks through both.

Part 1 — Create an API Token

Why a Token (not a Global API Key)?

Cloudflare offers two ways to authenticate: a Global API Key (your master key to everything) and scoped API Tokens (keys limited to specific actions). Always use a scoped API Token for tools like Dreadnought. If the token is ever compromised, an attacker can only touch DNS records — not your entire Cloudflare account.

Steps

  1. Log in to https://dash.cloudflare.com
  2. Click your profile icon in the top-right corner
  3. Go to My Profile → API Tokens
  4. Click Create Token
  5. Click Create Custom Token (at the bottom, not one of the templates)

Token Permissions

On the "Create Custom Token" page, configure:

Token name: something descriptive, e.g. Dreadnought DDNS

Permissions — add two rows:

Permission type Resource Action
Zone Zone Read
Zone DNS Edit

Click + Add more between rows if needed.

Zone Resources: - Include → All zones — simplest; works for any domain in your account - Include → Specific zone → [your domain] — more secure; the token can only touch that one zone

Repeat the "Specific zone" approach for each domain if you manage multiple zones separately. Or add multiple zone resources to one token.

IP Address Filtering (optional): If your server has a static IP, you can lock this token to only work from that IP. Leave it blank if your server IP is dynamic (ironic, but the DDNS tool itself has a dynamic IP during runtime — the important thing is the outbound IP of the Docker host calling the Cloudflare API).

TTL (optional): You can set an expiry date on the token. Leave blank for no expiry, or set a date if you prefer to rotate tokens on a schedule.

  1. Click Continue to summary
  2. Review the permissions and click Create Token
  3. Copy the token — this is the only time you'll see it. Paste it into your .env as CF_API_TOKEN.

If you lose the token, you'll need to create a new one. Old tokens can be deleted from the API Tokens page.

Verifying the Token Works

You can test the token from a terminal:

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

A successful response looks like:

{
  "result": {
    "id": "...",
    "status": "active"
  },
  "success": true
}

Part 2 — Find Your Zone ID

Each domain (zone) in Cloudflare has a unique Zone ID. You'll need this when adding a domain in the Dreadnought dashboard.

How to Find It

  1. Log in to Cloudflare
  2. Click on the domain you want to manage (e.g. example.com)
  3. You'll land on the Overview page for that domain
  4. Look at the right sidebar — scroll down if needed
  5. You'll see an API section with:
  6. Zone ID — a 32-character hex string like a1b2c3d4e5f6...
  7. Account ID
  8. Copy the Zone ID

The Zone ID is safe to store — it's not a secret on its own. It only becomes useful in combination with your API token.

Alternative: Find Zone IDs via API

If you have many domains and want to look them all up at once:

curl -X GET "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" | python3 -m json.tool

This returns a list of all zones your token has access to. Each entry includes the name (domain) and id (Zone ID).

Part 3 — Token Permissions Explained

Why Zone → Zone → Read?

Dreadnought uses this to look up zone details and resolve zone IDs by domain name. Even if you paste the Zone ID manually in the UI, this permission is needed for internal validation.

Why Zone → DNS → Edit?

This allows Dreadnought to create, update, and (optionally) delete A and AAAA records. It cannot touch MX, TXT, CNAME, or any other record type unless you're explicitly editing A/AAAA records.

What Dreadnought Does NOT Touch

  • Your Cloudflare account settings
  • Your billing or plan
  • Cloudflare Pages, Workers, R2, or any other product
  • MX, TXT, CNAME, NS, or any other DNS record type
  • Cloudflare proxying settings for records it doesn't manage

Rotating Your Token

It's good practice to rotate API tokens periodically. When you're ready:

  1. Create a new token in Cloudflare (follow the steps above)
  2. Update CF_API_TOKEN in your .env file
  3. Restart the app: bash docker compose restart api worker
  4. Delete the old token from Cloudflare's API Tokens page

Next Steps