Test a Cloudflare Global API Key Connection with PowerShell

When you are automating Cloudflare tasks, it is useful to confirm that your credentials work before running a larger script. This small PowerShell script tests a Cloudflare Global API Key by calling the Cloudflare accounts endpoint and printing the API response.

The script uses the legacy Global API Key authentication style:

X-Auth-Email: your Cloudflare account email
X-Auth-Key: your Cloudflare Global API Key

Cloudflare recommends API tokens for new automation because tokens can be scoped to specific permissions and resources. Global API Keys still work for accounts that have them, but they carry the same permissions as the user account. Use this script when you specifically need to test Global API Key access.

What the Script Does

The Test-CloudflareAPIKey.ps1 script:

• Reads a Cloudflare account email placeholder.
• Reads a Cloudflare Global API Key placeholder.
• Builds the required Cloudflare API headers.
• Calls https://api.cloudflare.com/client/v4/accounts.
• Prints the JSON response if the connection works.
• Prints the PowerShell exception message if the request fails.

Global API Key vs API Token

A Global API Key uses both your Cloudflare email address and the global key value. In PowerShell, the headers look like this:

$Headers = @{
    "X-Auth-Email" = $CloudflareEmail
    "X-Auth-Key"   = $GlobalApiKey
    "Content-Type" = "application/json"
    "Accept"       = "application/json"
}

An API token uses a bearer token header instead and does not need your email address:

$Headers = @{
    "Authorization" = "Bearer YOUR_API_TOKEN"
    "Content-Type"  = "application/json"
    "Accept"        = "application/json"
}

If you are writing new Cloudflare automation, use an API token whenever possible. If you are testing an older script that expects X-Auth-Email and X-Auth-Key, this article covers that path.

Get the Cloudflare Email and Global API Key

Use the email address for the Cloudflare user that owns the Global API Key.

To view the Global API Key in Cloudflare:

1. Log in to the Cloudflare dashboard. 2. Open the user profile menu. 3. Go to **API Tokens**. 4. Find the **API Keys** section. 5. View the **Global API Key**.

Do not paste a real key into documentation, screenshots, tickets, or public repositories. If a Global API Key is exposed, rotate it immediately.

Configure the Script

Open Test-CloudflareAPIKey.ps1 and replace the placeholder values:

$CloudflareEmail = "[email protected]"
$GlobalApiKey = "PUT_YOUR_REAL_GLOBAL_API_KEY_HERE"

Keep the quotes around both values.

How to Run the Script

Generic command:

.\script_location\scriptname.ps1

Concrete example:

Set-Location C:\Scripts\Cloudflare
.\Test-CloudflareAPIKey.ps1

If PowerShell blocks the script, see:

Make Sure PowerShell Scripts Can Run on Windows

Check the Result

If the credentials work, Cloudflare returns account data in JSON format. The response should include a top-level success value and a result array.

The script prints the response with:

$Response | ConvertTo-Json -Depth 10

If the request fails, check these common causes:

• The email address does not match the Cloudflare user that owns the Global API Key.
• The Global API Key was copied incorrectly.
• The account email address has not been verified.
• The key was rotated after it was copied.
• The network or server blocks outbound HTTPS requests to api.cloudflare.com.

Important Notes

• Prefer scoped API tokens for new Cloudflare automation.
• Treat the Global API Key like a password with broad account access.
• Store credentials in a secure secret store for production automation.
• Do not commit real Cloudflare credentials into a Git repository.
• Rotate the key immediately if it is exposed.

The full script is below. Save it as Test-CloudflareAPIKey.ps1.

PowerShell Script

#region Settings
Clear-Host
Push-Location $PSScriptRoot
 
$CloudflareEmail = "PUT_YOUR_CLOUDFLARE_EMAIL_HERE"
$GlobalApiKey = "PUT_GLOBAL_API_KEY_HERE"
#endregion Settings

#region Create Header
Write-Host "Creating Cloudflare Global API Key headers."

$Headers = @{
    "X-Auth-Email" = $CloudflareEmail
    "X-Auth-Key"   = $GlobalApiKey
    "Content-Type" = "application/json"
    "Accept"       = "application/json"
}

Write-Host "Header created using Global API Key auth."
#endregion Create Header

#region Test Global API Key
Write-Host "Testing Cloudflare Global API Key by listing accounts."

try {
    $Response = Invoke-RestMethod `
        -Method GET `
        -Uri "https://api.cloudflare.com/client/v4/accounts" `
        -Headers $Headers `
        -TimeoutSec 30

    $Response | ConvertTo-Json -Depth 10
}
catch {
    Write-Host "Global API Key test failed:" -ForegroundColor Red
    Write-Host $_.Exception.Message -ForegroundColor Red
}
#endregion Test Global API Key

References

• Cloudflare API calls and bearer tokens
• Cloudflare Global API Key documentation
• Cloudflare token formats