Cloudflare Integration

Connect Cloudflare to enable agents to query zones, DNS records, alert history, and infrastructure details during investigations.

Capabilities

Once connected, agents can:

Capability	Description
List Zones	Browse and search domains managed in your Cloudflare account
View Zone Details	Get full zone configuration including SSL and security settings
List DNS Records	Query DNS records by type, name, or content for any zone
View Alert History	Access notification alert history for incident investigation

Prerequisites

• A Cloudflare account with API access
• An API Token (User Token, Account Token, or Global API Key)
• Your Account ID

Authentication Methods

Cloudflare supports three authentication methods. Choose the one that best fits your use case.

Account API Token (Recommended)

Account API Tokens are not tied to any individual user. They act as a service principal for the account. This makes them ideal for integrations, because they continue to work independently of any one person's access.

Required fields:

• API Token / Global API Key: Your Account API Token
• Account ID: Your Cloudflare Account ID

Leave the Auth Email field blank.

info

Account API Tokens require Super Administrator permissions to create. If you don't have Super Admin access, use a User API Token instead.

User API Token

User API Tokens are scoped tokens created by individual users. They inherit a subset of that user's permissions and are best for ad hoc tasks or when you don't have Super Admin access.

Required fields:

• API Token / Global API Key: Your User API Token
• Account ID: Your Cloudflare Account ID

Leave the Auth Email field blank.

warning

User API Tokens are tied to the user who created them. If that user is removed from the Cloudflare account, the token stops working. For long-lived integrations, prefer Account API Tokens.

Global API Key (Legacy)

The Global API Key is Cloudflare's legacy authentication method. It grants full access to your entire account with no way to restrict permissions.

Required fields:

• API Token / Global API Key: Your Global API Key
• Auth Email: The email address associated with your Cloudflare account
• Account ID: Your Cloudflare Account ID

warning

The Global API Key grants unrestricted access to your entire Cloudflare account. It cannot be scoped, expired, or IP-restricted. We strongly recommend using an Account API Token or User API Token instead.

Comparison

Feature	Account API Token	User API Token	Global API Key
Tied to a user?	No (service principal)	Yes	Yes
Fine-grained permissions	Yes	Yes	No (full access)
Expiration / TTL	Yes	Yes	No
IP restrictions	Yes	Yes	No
Survives user removal	Yes	No	No
Auth header	Authorization: Bearer	Authorization: Bearer	X-Auth-Key + X-Auth-Email
Best for	Integrations, CI/CD	Ad hoc tasks, scripting	Not recommended

Setup

Option A: Account API Token (Recommended)

1

Navigate to Account API Tokens

1. Log in to the Cloudflare dashboard
2. Click the account dropdown (top-left) and select Manage Account
3. Go to API Tokens in the left sidebar
4. Scroll to the Account API Tokens section
5. Click Create Token

2

Configure Token Permissions

Create a custom token with these read-only permissions:

Permission Group	Permission	Access
Account	Account Settings	Read
Account	Notifications	Read
Zone	Zone	Read
Zone	DNS	Read

Optionally add restrictions:

• IP Address Filtering — Restrict to your server IP range
• TTL — Set an expiration date

tip

You can also start from the Read all resources template and restrict the permissions to only what's needed.

3

Copy the Token

Click Create Token. Cloudflare shows the token secret only once. Copy it immediately and store it securely.

Check that the token works:

curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  --header "Authorization: Bearer YOUR_TOKEN"

You should see "status": "active" in the response.

4

Find Your Account ID

1. In the Cloudflare dashboard, go to any domain's Overview page
2. Find Account ID in the right sidebar under API
3. Copy the Account ID

5

Add Integration in Autoheal

1. Go to Integrations in Autoheal
2. Click Cloudflare
3. Enter a name (e.g., "Production Cloudflare")
4. Complete these fields:
   • API Token / Global API Key: The Account API Token you just created
   • Auth Email: Leave blank
   • Account ID: Your Cloudflare Account ID
5. Click Test Connection to check the connection, then click Save

Option B: User API Token

1

Navigate to User API Tokens

1. Log in to the Cloudflare dashboard
2. Click your profile icon (top-right) and select My Profile
3. Go to the API Tokens tab
4. Click Create Token

2

Configure Token Permissions

Choose one of these approaches:

Quick start: Select the Read all resources template, then click Continue to summary.

Custom (recommended): Click Create Custom Token and add these permissions:

Permission Group	Permission	Access
Account	Account Settings	Read
Account	Notifications	Read
Zone	Zone	Read
Zone	DNS	Read

Under Account Resources, select All accounts (or pick specific accounts).

Under Zone Resources, select All zones (or pick specific zones if you want to restrict access).

Optionally set:

• Client IP Address Filtering — Restrict usage to specific IPs
• TTL — Set start and end dates for the token

3

Copy the Token

Click Create Token. Cloudflare shows the token secret only once. Copy it immediately.

Check that the token works:

curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  --header "Authorization: Bearer YOUR_TOKEN"

4

Find Your Account ID

1. In the Cloudflare dashboard, go to any domain's Overview page
2. Find Account ID in the right sidebar under API
3. Copy the Account ID

5

Add Integration in Autoheal

1. Go to Integrations in Autoheal
2. Click Cloudflare
3. Enter a name (e.g., "Production Cloudflare")
4. Complete these fields:
   • API Token / Global API Key: The User API Token you just created
   • Auth Email: Leave blank
   • Account ID: Your Cloudflare Account ID
5. Click Test Connection to check the connection, then click Save

Option C: Global API Key (Legacy)

1

Find Your Global API Key

1. Log in to the Cloudflare dashboard
2. Click your profile icon (top-right) and select My Profile
3. Go to the API Tokens tab
4. In the Global API Key section, click View
5. Enter your Cloudflare password to reveal the key
6. Copy the key

2

Find Your Account ID

1. In the Cloudflare dashboard, go to any domain's Overview page
2. Find Account ID in the right sidebar under API
3. Copy the Account ID

3

Add Integration in Autoheal

1. Go to Integrations in Autoheal
2. Click Cloudflare
3. Enter a name (e.g., "Production Cloudflare")
4. Complete these fields:
   • API Token / Global API Key: Your Global API Key
   • Auth Email: The email address associated with your Cloudflare account
   • Account ID: Your Cloudflare Account ID
5. Click Test Connection to check the connection, then click Save

Required Permissions

When using a scoped API Token (Account or User), create it with at least these permissions:

Permission	Why It's Needed
Zone:Read	List and view zone details
DNS:Read	List and view DNS records
Account Settings:Read	Access account-level information
Notifications:Read	View alert notification history

tip

Create a dedicated API token for Autoheal with only read permissions. Avoid granting write or delete access unless you have a specific reason to do so.

Finding Your Account ID

You can find your Account ID in several places:

1. Domain Overview: Go to any domain → Overview → right sidebar under API
2. Account Home: Go to Account Home → the URL contains your account ID: https://dash.cloudflare.com/<account-id>
3. Workers & Pages: Navigate to Workers & Pages → the right sidebar shows the Account ID

Example Queries

Once connected, you can ask an agent questions like:

List all zones in my Cloudflare account

Show me the DNS records for example.com

What A records point to 192.168.1.1?

Show me recent Cloudflare alerts

Troubleshooting

401 Unauthorized

• Check that the API Token or Global API Key is correct and has not been revoked
• If you use a Global API Key, check that the Auth Email field contains the correct Cloudflare account email
• If you use an API Token (User or Account), check that the Auth Email field is blank
• Check that the token has the required permissions
• Check that the token has not expired (see the TTL settings)

Invalid format for Authorization header

• This error typically means you are using a Global API Key but the Auth Email field is empty
• Global API Keys require the Auth Email. Enter the email address associated with your Cloudflare account
• If you intended to use an API Token, check that you copied the scoped token (not the Global API Key)

403 Forbidden

• The API token may not have access to the requested resource
• Check that the Account ID matches the account the token was created for
• Check that zone-level permissions include the zones you're querying
• Account API Tokens: Some Cloudflare products are not compatible with account tokens (e.g., Page Rules, Registrar, Turnstile). If you get a 403 on specific endpoints, try a User API Token instead

No Zones Found

• Check that the Account ID is correct
• Check that the API token has Zone:Read permission
• Check that the account has active zones

Connection Timeout

• Cloudflare API uses https://api.cloudflare.com/client/v4/. Check network connectivity
• Check if corporate firewalls or proxies are blocking API access

Token stopped working after user was removed

• User API Tokens are tied to the user who created them. If that user is removed from the account, the token is invalidated
• Create an Account API Token instead. Account API Tokens are not tied to any user and persist through team changes
• Account API Tokens require Super Administrator permissions to create