Cloudflare Workers

Cloudflare Workers Integration (Get IP Addresses) allows your product to securely retrieve and manage real-time visitor IP addresses for requests passing through Cloudflare's global edge network.

This integration is valuable for use cases such as security analytics, threat intelligence, geo-fencing, auditing, rate-limiting, or custom access control.

Using Cloudflare Workers, you can extract IPs at the edge — before requests ever reach your origin servers — enabling low-latency and privacy-respecting visibility into client connections.

Credentials Needed

To deploy and interact with Cloudflare Workers for IP collection, you need credentials associated with your Cloudflare Account.

Required credentials:

• Cloudflare Account ID
• Cloudflare Zone ID (optional, if binding to specific domain)
• Cloudflare API Token

Always use API Tokens with least privilege (only for Workers read/write) instead of the global API key.

Permissions Needed / API Scopes

Your token must have Worker-related permissions to deploy, read, and manage scripts.

Permission	Scope	Description
Account.Workers Scripts Write	Account	Create or update Workers scripts
Account.Workers Scripts Read	Account	Retrieve deployed Workers
Account.Workers Tail Read	Account	Debug or log worker output (optional)
Zone: Read (optional)	Specific Zone	Read zone details if tied to a domain
Zone: Edit (optional)	Specific Zone	Deploy worker routes under a domain

Minimum Required Permissions: Account.Workers Scripts Read and Account.Workers Scripts Write

Creating Users / Access Tokens

Step 1: Generate an API Token

1. Go to Cloudflare Dashboard → Profile → API Tokens: https://dash.cloudflare.com/profile/api-tokens
2. Click Create Token → Create Custom Token.
3. Under Permissions, assign:
   • Workers Scripts → Read, Write
   • (Optional) Zone → Read/Edit if you deploy the Worker under a domain route.
4. Under Account Resources, select your account.
5. Click Continue to Summary → Create Token.
6. Copy the API Token — it will only be shown once.

Deploying the Worker (Get Client IP Example)

You can use the Cloudflare REST API or the wrangler CLI to deploy your Worker that captures client IPs.

Example Worker Script

export default {
  async fetch(request) {
    const clientIP = request.headers.get("CF-Connecting-IP");
    const country = request.headers.get("CF-IPCountry");
    const asn = request.headers.get("CF-IPAS-Name");

    const result = {
      ip: clientIP,
      country,
      asn,
      timestamp: new Date().toISOString(),
    };

    return new Response(JSON.stringify(result), {
      headers: { "Content-Type": "application/json" },
    });
  },
};

This Worker retrieves the client's public IP address, country, and ASN directly from Cloudflare's edge headers.

Deploy Using Wrangler CLI

1. Install Wrangler (Cloudflare CLI):

npm install -g wrangler

2. Authenticate with Cloudflare:

wrangler login

3. Create a Worker:

wrangler init get-client-ip
cd get-client-ip

4. Replace index.js content with the Worker code above.

5. Deploy the Worker:

wrangler deploy

The command returns a URL such as:

https://get-client-ip.<your-subdomain>.workers.dev

Test the Worker

curl https://get-client-ip.<your-subdomain>.workers.dev

Example Response:

{
  "ip": "203.0.113.25",
  "country": "IN",
  "asn": "AS15169 Google LLC",
  "timestamp": "2025-10-13T12:45:00Z"
}

You've successfully retrieved client IP and metadata through your Cloudflare Worker.

Save the Results in the Platform and Create Connection

In your platform's connector setup, securely store:

• CLOUDFLARE_ACCOUNT_ID
• CLOUDFLARE_API_TOKEN
• (Optional) CLOUDFLARE_ZONE_ID
• WORKER_URL (e.g., https://get-client-ip.workers.dev)

Label the connection as Cloudflare Worker (Get IP Address).

Test the connection by fetching sample IP data.

Save the validated configuration for further use in analytics or security modules.

Best Practices

• Use least-privilege tokens (Workers-only).
• Store all credentials securely in a secret vault or Cloudflare KV Secrets.
• Rotate API tokens every 90 days.
• Avoid logging IPs directly in Workers — store or forward them securely.
• Use Cloudflare Access or Zero Trust policies for authenticated IP data access.
• Use Edge Rate Limiting or Firewall Rules to prevent abuse.
• For privacy compliance (GDPR, CCPA), anonymize or truncate IPs before storage.
• Monitor usage and performance using Workers Analytics in the Cloudflare Dashboard.
• Enable Workers Tail for debugging logs in real time:

wrangler tail get-client-ip

• If multiple Workers need IP access, centralize this logic via an Edge API Gateway Worker.