pfSense Cloudflare Dynamic DNS: API Token Setup and Fixes

  • Post author:Frank Joseph
  • Post published:
  • Post last modified:
  • Post category:pfSense
  • Reading time:9 mins read

To set up pfSense Cloudflare dynamic DNS, add the record in Cloudflare first and create an API token from the Edit zone DNS template. Then add a Cloudflare client under Services > Dynamic DNS in pfSense, with your Zone ID in Username and the token in Password. The labels below are from pfSense CE 2.9.0, the current release as of November 2026.

Dynamic DNS tracks the external IP address of your home network and updates a hostname whenever your ISP changes it, so a name like home.example.com always points back home. With a static external IP, DDNS only puts a name on it, but most people have a dynamic one.

You’ll need a domain that uses Cloudflare for its DNS. If you don’t have one, you can set up DDNS on pfSense with DuckDNS instead. If your domain isn’t on Cloudflare yet, my 2021 video below covers adding one.

Add the DNS Record in Cloudflare First

The pfSense Dynamic DNS Cloudflare client only updates a record that already exists. It looks the record up by name and type and changes its IP address. Create it first with any IP address, since pfSense overwrites it on the first update.

1. Log in to Cloudflare, select your domain, open its DNS Records page and select Add record.

2. Set Type to A and enter the subdomain you’d like to use in Name (home, for example, or @ for the root domain). Put any placeholder in IPv4 address, set Proxy status to DNS only, and select Save.

Cloudflare DNS management in 2022 adding an A record named ddns pointing to 1.1.1.1 with the proxy status set to DNS only
The A record from the January 2022 version of this guide. Cloudflare’s layout has changed since, but not the fields.

Cloudflare in pfSense updates an A record and Cloudflare (v6) updates an AAAA record, so the record type has to match the service type you pick later. For both IPv4 and IPv6, create an A and an AAAA record with the same name and add two clients in pfSense, one of each type.

pfSense hides Wildcards for Cloudflare, so for more names (a wildcard too), add CNAME records in Cloudflare that point to this hostname, set to DNS only for a VPN.

Create the Cloudflare API Token

A token from the Edit zone DNS template can edit DNS records on the one zone you pick and nothing else, which is all pfSense needs. It’s the same Zone / DNS / Edit permission I gave the Nginx Proxy Manager DNS challenge token in my July 2024 video.

In the video I made on this, published in January 2022 on pfSense 2.5.2, I used the Global API Key and said on camera that a scoped token didn’t work at that point. I still showed the Edit zone DNS template for anyone who wanted to try it. pfSense’s own help text was on my screen in that same recording. The Username field read “Cloudflare: Enter email for Global API Key or (optionally) Zone ID for API token,” and the token code was already in 2.5.2.

1. In Cloudflare, select My Profile, then API Tokens, and finally, Create Token.

2. Choose the Edit zone DNS template. Under Zone Resources, set Include, Specific zone and your domain, then select Continue to summary and Create Token.

3. Copy the token and save it somewhere safe. Cloudflare only shows it once, and new tokens start with cfut_.

4. Select your domain, scroll to the API section toward the bottom of its Overview page, and copy the Zone ID with the copy button next to it.

The Zone ID is why that template is enough. With Username blank, pfSense first looks the zone up by name, which needs the Zone Read permission the template leaves out. With the Zone ID there, it skips that lookup (adding Zone > Zone > Read to the token is the other fix).

Using the Global API Key Instead

The Global API Key is under My Profile > API Tokens > API Keys, where you select View next to Global API Key. With it, your Cloudflare account email goes in Username instead of the Zone ID. Cloudflare says the key “has access to all of a user’s resources” and is “not recommended for new customers.” That’s the same reason I gave in that video for wanting a token, as pfSense only needs the DNS section and the key gives it everything.

Add the Cloudflare Dynamic DNS Client in pfSense

1. Select Services, then Dynamic DNS. On the Dynamic DNS Clients tab, select Add.

pfSense CE 2.9.0 Services menu open with Dynamic DNS in the list, over the empty Dynamic DNS Clients tab and its Add button

2. Set Service Type to Cloudflare (or Cloudflare (v6) for an AAAA record), and leave Interface to monitor on WAN and Check IP Mode on Automatic (default).

3. Enter the subdomain in the Hostname box and your Cloudflare domain in the Domain name box beside it, for example home and example.com. pfSense joins the two boxes into the record name it looks up (home.example.com), so don’t put the full hostname in the first box, and enter @ as the hostname for the root domain.

4. Leave Cloudflare Proxy (Enable Proxy) unticked unless you want Cloudflare’s proxy, which is covered in the next section.

pfSense CE 2.9.0 Dynamic DNS client form with Service Type Cloudflare, Interface to monitor WAN, Check IP Mode Automatic (default), Hostname home, Domain name example.com and Enable Proxy unticked

5. Paste the Zone ID into Username and the token into Password and Confirm. Leave TTL blank (pfSense sends it as Auto), add a Description, and select Save.

pfSense CE 2.9.0 Cloudflare Dynamic DNS form with an example Zone ID in Username, a masked token in Password and Confirm, TTL blank and the Cloudflare help text under each field

If pfSense sits behind another router and its WAN address is private, Automatic (default) fetches the public IP from the Check IP service instead.

What pfSense Does With the Username Field

Username is the field to get right, because pfSense decides how to sign in from what you type there:

What’s in UsernameWhat pfSense doesUse it with
An email address (contains @)Sends it with the Password as the Global API KeyThe Global API Key
NothingSends the Password as a token and looks the zone up by its domain nameA token that can also read the zone
Anything elseTreats it as the Zone ID and sends the Password as a tokenA token (the setup above)

The trap is the last row: a Cloudflare username that isn’t an email address is sent as a Zone ID too, and the update fails. The older version of this guide said to enter your Cloudflare username, which is right only if you read it as the email you sign in with.

Cloudflare Proxy or DNS Only

The Enable Proxy checkbox in pfSense decides the record’s proxy status, not the toggle in Cloudflare. pfSense sends it with every update, so if you set the record to proxied in Cloudflare and leave the box unticked in pfSense, the next update sets it back to DNS only (and the other way around).

A proxied record (the orange cloud) resolves to Cloudflare’s IP addresses and Cloudflare forwards the traffic, which hides your real IP. DNS only (the gray cloud) returns your real IP. Cloudflare only proxies HTTP and HTTPS on a short list of ports (80, 443, 8080 and 8443 among them), and anything else needs the record set to DNS only.

A hostname you use as a VPN endpoint has to be DNS only, because OpenVPN’s default of UDP 1194 and WireGuard aren’t on that list. Leave Enable Proxy unticked if you’re going to set up OpenVPN on pfSense or set up WireGuard on pfSense with it. That was the point of the hostname in the 2022 video, too, and the pfSense OpenVPN tutorial I published two weeks later used it.

Tick Enable Proxy only for a hostname that serves a website over HTTP or HTTPS on one of Cloudflare’s ports.

Check That It Works and Fix Common Errors

After you save, pfSense goes back to the Dynamic DNS Clients list. A green check under Status and your WAN IP in green under Cached IP mean the entry is up to date with Cloudflare, and the Cloudflare record should now show that IP instead of the placeholder. An empty Status and N/A under Cached IP, like below, mean no update has succeeded yet.

pfSense CE 2.9.0 Dynamic DNS Clients list with a saved Cloudflare entry for home.example.com that hasn't updated yet: Status empty and Cached IP N/A

The list doesn’t say why. pfSense logs its error messages at the Info level, so set Default Log Level to Info under Status > System Logs > Settings and save. Then open the entry with the pencil icon under Actions and select Save & Force Update.

pfSense CE 2.9.0 Cloudflare Dynamic DNS entry open for editing, with the Save and Save & Force Update buttons

Check Status > System Logs > System > General for phpDynDNS lines like these:

  • Zone or Host ID was not found, check the hostname. pfSense couldn’t find a record with that name and type. Check that the record exists in Cloudflare, that its type matches the service (A for Cloudflare, AAAA for Cloudflare (v6)), and that the two hostname boxes are split correctly. With a token, also check that Username holds the Zone ID and isn’t blank.
  • Invalid Credentials! Don’t forget to use API Key for password field with Cloudflare. Cloudflare rejected the email and Global API Key pair (its error 9103). Copy the key again and check that Username is your account email.
  • UNKNOWN ERROR followed by Cloudflare’s own message. At the default log level, its full reply also shows as an ERROR line with PAYLOAD and its error code. A rejected token or Zone ID comes back this way, so copy both again in full. If the PAYLOAD says “Invalid format for X-Auth-Key header”, there’s an email in Username with a token, so put the Zone ID there instead. For more detail, tick Enable verbose logging on the entry.
pfSense CE 2.9.0 General system log showing the Cloudflare Dynamic DNS client's error line after a forced update with example credentials

A report on the Netgate forum describes the Zone ID and token setup failing on pfSense 2.8.1 with UNKNOWN ERROR and a cached IP of 0.0.0.0. The reporter suspected a token written into the configuration by a restore or a script, not typed into this form, and the CE 2.9.0 release notes don’t mention it. If you see it, enter the token in Password and Confirm again and save, and if it still fails, use the Global API Key.

Once the entry is green, change the record’s IP in Cloudflare to something else, then open the entry and select Save & Force Update. If your real IP comes back, it’s working. Security changes all the time and nothing here is a guarantee, so keep pfSense updated and only expose what you actually need.

Frank Joseph

I'm Frank, founder of WunderTech. I've been working in enterprise IT for 15+ years and running home labs for nearly a decade — every tutorial on this site is tested on hardware I actually own, including Synology NAS units, a DIY TrueNAS server, a Proxmox cluster, a full UniFi network, and more. I hold a BS in Computer Information Systems and an MBA, but most of what you'll read here comes from my home lab, not a classroom. You can also find video versions of these tutorials on my YouTube channel.