Connecting to Cloudflare

5 min readUpdated May 20, 2026

Before WP WAF Manager can do anything useful, it needs permission to talk to your Cloudflare account. There are two ways to authenticate, and the plugin supports both:

API Token (recommended) — a scoped credential you create just for this plugin
Email + Global API Key — your account email plus the legacy global key

Both work fine, but we strongly recommend using an API Token. Tokens are scoped to only the permissions the plugin actually needs, can be revoked independently without affecting anything else, and don’t expose your full account if something ever goes wrong. The Global API Key, by contrast, has unrestricted access to your entire Cloudflare account — if it leaks, an attacker can do anything you can do.

Use Email + Global Key only if you’re troubleshooting or if a token genuinely won’t work for your setup.

Connecting an account

The standard way is through the plugin UI — go to WP WAF Manager and use the Connect Cloudflare Account form. Your credentials are encrypted at rest using libsodium with a key derived from your site’s AUTH_KEY, so they’re never stored as plaintext in the database.

Advanced: wp-config.php constants

If you prefer credentials to never touch the database at all, you can define them directly in wp-config.php. This is especially useful for agencies managing multiple client sites, or for environments where database access should be kept strictly separate from API credentials.

Add your constants above the /* That's all, stop editing! */ line.

Single account — API Token

php

define( 'WPWAF_API_LABEL', 'My Agency' ); // optional
define( 'WPWAF_API_TOKEN', 'your-token-here' );

Single account — Email + Global API Key

php

define( 'WPWAF_API_LABEL', 'My Agency' ); // optional
define( 'WPWAF_API_EMAIL', '[email protected]' );
define( 'WPWAF_API_KEY',   'your-global-api-key-here' );

Multiple accounts with labels

php

define( 'WPWAF_ACCOUNTS', [
    [ 'label' => 'Main Site', 'api_token' => 'token-one' ],
    [ 'label' => 'Client A',  'api_token' => 'token-two' ],
    [ 'label' => 'Client B',  'api_email' => '[email protected]', 'api_key' => 'global-key-here' ],
] );

When WPWAF_ACCOUNTS is defined it takes priority over the single-account constants. The first account in the array is always the active one. Mixing API Token and Email + Key auth within the same array is fully supported.

Constant-defined accounts appear in the plugin UI as read-only — they cannot be edited or removed from within WordPress, which also means they can’t be accidentally deleted or overwritten.

Option 1 — API Token (recommended)#

Step 1 — Open the Cloudflare token page#

Log into Cloudflare and go to My Profile → API Tokens, or jump straight to:

https://dash.cloudflare.com/profile/api-tokens

Click Create Token, then scroll down and choose Create Custom Token (don’t use one of the pre-built templates — they don’t grant exactly the right scopes).

Step 2 — Set the permissions#

Give the token a name like WP WAF Manager so you’ll recognise it later, then add the following permissions one at a time:

Here’s the updated table and notes:

Type	Resource	Access
Zone	WAF	Edit
Zone	Zone	Edit
Zone	Zone Settings	Edit
Zone	Analytics	Read
Zone	DNS	Edit
Zone	Cache Purge	Purge
Account	Account Firewall Access Rules	Edit
Account	Email Routing Addresses	Edit

A quick note on what each one is for:

Zone → WAF → Edit — create and toggle the firewall rules

Zone → Zone → Edit — list your zones in the dashboard

Zone → Zone Settings → Edit — manage Under Attack Mode, Development Mode, SSL, cache, and other zone-level settings

Zone → Analytics → Read — display zone analytics in the Zone Status module

Zone → DNS → Edit — read and edit DNS records

Zone → Cache Purge → Purge — purge zone cache from Zone Controls

Account → Account Firewall Access Rules → Edit — manage account-wide IP Access Rules

Account → Email Routing Addresses → Edit — manage catch-all and address forwarding

Step 3 — Set the resources#

Under Account Resources, choose Include → All accounts (or pick a specific account if you only want this token to work on one).

Under Zone Resources, choose Include → All zones from an account and select the right account, or All zones if you want it to cover everything.

Step 4 — Create and copy the token#

Click Continue to summary, review the permissions, then click Create Token.

Cloudflare will show you the token once. Copy it immediately and paste it somewhere safe — if you close the page without copying, you’ll have to delete the token and create a new one.

Step 5 — Add it to WP WAF Manager#

In your WordPress admin:

Go to WAF Manager → Settings.
Choose API Token as the authentication method.
Paste your token into the API Token field.
Click Save & Test Connection.

If everything’s right, you’ll see a green confirmation and your zones will start populating in the dashboard. If you get an error, the most common cause is a missing permission — go back and double-check the table in Step 2.

Option 2 — Email + Global API Key#

If you’d rather use your account email and Global API Key, the plugin supports it.

Step 1 — Get your Global API Key#

Go to My Profile → API Tokens at https://dash.cloudflare.com/profile/api-tokens.
Scroll down to the API Keys section at the bottom.
Next to Global API Key, click View.
Confirm your password and complete the captcha.
Copy the key.

Step 2 — Add it to WP WAF Manager#

In WP admin, go to WAF Manager → Settings.
Choose Email + Global API Key as the authentication method.
Enter the email address you use to log into Cloudflare.
Paste the Global API Key into the key field.
Click Save & Test Connection.

That’s it — the plugin will authenticate the same way, and every feature works identically.

The Global API Key gives whoever holds it complete, unrestricted control over your Cloudflare account — DNS, billing, team members, everything. If your WordPress site is ever compromised and the database is dumped, that key goes with it. An API Token, by contrast, can only do the specific things you authorised, and you can revoke it from Cloudflare in one click without touching anything else.

If you do go the Global Key route, treat your WordPress site’s security with extra care, and rotate the key periodically.

Where to next#

Quick Start — set up your first WAF rule