Skip to main content

Cloudflare

Cloudflare is a global network platform that provides DNS management, CDN, DDoS protection, and edge computing services. With Cloudflare, organizations can secure and accelerate their websites, manage DNS records, deploy serverless applications with Workers, host static sites with Pages, store data in R2 object storage, and use Workers KV for low-latency key-value storage.

Authentication Types​

Cloudflare supports 1 authentication method:

  • API Token - Create a scoped API token with specific permissions for your use case.
    • Pros: Secure, fine-grained permission control, can be scoped to specific zones or accounts, supports IP filtering
    • Cons: Requires Cloudflare account access to create tokens
    • Best for: All use cases - recommended by Cloudflare for security and flexibility

Setting up API Token​

To use Cloudflare with Webrix, you need to create an API token with appropriate permissions.

1. Create an API Token​

  1. Log in to your Cloudflare dashboard at https://dash.cloudflare.com

  2. Click on your profile icon in the top right, then select My Profile

  3. Navigate to API Tokens in the left sidebar

  4. Click Create Token

  5. You have two options:

    Option A: Use a Template

    • For most use cases, select Edit zone DNS template for DNS management
    • For Workers/Pages, select Edit Cloudflare Workers template
    • Click Use template

    Option B: Create Custom Token (Recommended for full access)

    • Click Create Custom Token
    • Give your token a descriptive name (e.g., "Webrix Integration")
    • Configure permissions based on what you need:

  6. Click Continue to summary

  7. Review your token configuration and click Create Token

  8. IMPORTANT: Copy the token immediately - it will only be shown once!

    • The token starts with a prefix and is a long alphanumeric string
    • Store it securely (password manager, secrets vault, etc.)
    • You cannot retrieve this token again - you'll need to create a new one if lost

2. Find Your Account ID and Zone IDs​

Many Cloudflare API operations require an Account ID or Zone ID:

Finding Account ID:

  1. In the Cloudflare dashboard, go to any zone
  2. Scroll down in the right sidebar under API section
  3. Copy your Account ID

Finding Zone IDs:

  1. Go to the specific domain/zone in Cloudflare dashboard
  2. In the right sidebar under API section
  3. Copy the Zone ID for that domain

Alternatively, you can use the List Zones tool after authentication to discover all your zone IDs programmatically.

3. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select Cloudflare and click Use

  3. Under Authentication Type, select API Key (this is API Token authentication)

  4. Paste your API token in the API Key field

  5. Click Save Changes

4. Test the Connection​

  1. After saving, test the connection by running a simple operation
  2. Try the List Zones tool to verify access
  3. You should see your Cloudflare zones listed

Common Use Cases​

Managing DNS Records​

Use Cloudflare's DNS tools to programmatically manage your domain's DNS records:

  • List DNS Records: Discover existing DNS configuration
  • Create DNS Record: Add new A, AAAA, CNAME, TXT, MX, or other records
  • Update DNS Record: Modify existing records (change IPs, toggle proxy status)
  • Delete DNS Record: Remove unwanted records
  • Export/Import DNS: Backup or migrate DNS configurations in BIND format

Example workflow: Update a website's IP address by finding the A record, then updating it with the new IP.

Deploying Workers​

Cloudflare Workers allow you to run serverless JavaScript/TypeScript at the edge:

  • Deploy Worker: Upload or update Worker scripts
  • List Workers: See all deployed Workers
  • Manage Routes: Control which URL patterns trigger which Workers
  • Get Worker Script: Download existing Worker code for review or backup

Example workflow: Deploy a Worker to handle API requests, then create a route to direct traffic matching /api/* to that Worker.

Managing Pages Deployments​

Cloudflare Pages hosts static sites and JAMstack applications:

  • List Pages Projects: View all your Pages projects
  • Create Deployment: Trigger new deployments from your CI/CD
  • Rollback Deployment: Quickly revert to a previous working deployment
  • Get Deployment Logs: Debug build failures or investigate deployment issues

Example workflow: Automatically trigger a new deployment when code is pushed, then check deployment logs to verify success.

Working with R2 Storage​

R2 is Cloudflare's S3-compatible object storage:

  • List R2 Buckets: See all your storage buckets
  • Create Bucket: Set up new storage containers
  • Generate Temporary Credentials: Create S3-compatible credentials for programmatic access

Note: For object operations (uploading/downloading files), use S3-compatible APIs with the generated credentials.

Example workflow: Create an R2 bucket for storing user uploads, then generate temporary credentials for your application to use with AWS SDK.

Using Workers KV​

Workers KV provides low-latency key-value storage at the edge:

  • List KV Namespaces: View all your KV namespaces
  • Create Namespace: Set up new KV storage
  • Read/Write Values: Store and retrieve data by key
  • List Keys: Discover what data is stored
  • Set Expiration: Configure automatic data expiration with TTL

Example workflow: Store API rate limiting data in KV, with automatic expiration after 1 hour.

Troubleshooting​

Invalid API Token​

API requests fail with 401 (Unauthorized) or 403 (Forbidden) errors.

Cause: The API token is invalid, expired, or doesn't have required permissions.

Solution:

  1. Verify the token is correctly copied (no extra spaces or characters)
  2. Check if the token has expired in Cloudflare dashboard → My Profile → API Tokens
  3. Verify the token has the necessary permissions for the operation you're trying to perform
  4. If using zone-scoped tokens, ensure you're accessing a zone the token has access to
  5. Create a new token if the current one is compromised or lost

Rate Limit Exceeded​

API requests fail with 429 (Too Many Requests) errors.

Cause: You've exceeded Cloudflare's API rate limits. The standard limit is 1,200 requests per 5 minutes per API token.

Solution:

  1. Check the Ratelimit and retry-after response headers
  2. Implement exponential backoff and retry logic in your workflows
  3. Reduce the frequency of API calls by batching operations where possible
  4. For enterprise customers, contact Cloudflare support to request higher limits
  5. Wait for the time specified in the retry-after header before retrying

Zone or Account ID Not Found​

Errors when trying to access zones or account-level resources.

Cause: Using an incorrect or inaccessible Zone ID or Account ID.

Solution:

  1. Verify the Zone ID by checking the Cloudflare dashboard → select zone → API section
  2. Verify the Account ID from the dashboard sidebar
  3. Use the List Zones tool to discover all accessible zones and their IDs
  4. Ensure your API token has access to the specific zone or account you're trying to access
  5. Check that the zone hasn't been removed or transferred to another account

DNS Record Not Found or Cannot Be Modified​

Errors when trying to update or delete DNS records.

Cause: Using an incorrect record ID, or the record has special restrictions.

Solution:

  1. Use List DNS Records to find the correct record ID
  2. Some records (like Cloudflare-managed records) cannot be modified or deleted
  3. Verify you have DNS Edit permissions in your API token
  4. For CNAME flattening or apex records, special rules may apply
  5. Check if the zone is active and not in a pending or moved state

Worker Deployment Failures​

Worker upload fails or Workers don't execute correctly.

Cause: Syntax errors, binding misconfigurations, or exceeding Workers limits.

Solution:

  1. Validate your Worker script syntax locally before deploying
  2. Check Worker size limits (1 MB for free plan, 5 MB for paid plans)
  3. Verify environment bindings (KV namespaces, R2 buckets) are correctly configured
  4. Use Get Deployment Logs for Pages to see detailed error messages
  5. Test Workers locally using Wrangler CLI before deploying via API
  6. Ensure your Worker doesn't exceed CPU time limits (10ms free, 50ms paid)

Pages Deployment Stuck or Failing​

Pages deployments don't complete or fail during build.

Cause: Build errors, incorrect build configuration, or timeout issues.

Solution:

  1. Use Get Deployment Logs to see the exact build error
  2. Verify build command and output directory are correct for your framework
  3. Check that all dependencies are properly specified in package.json
  4. Ensure environment variables required for build are configured in project settings
  5. Build timeouts: Free plan has 20 minutes, paid plans have 60 minutes
  6. For large builds, consider optimizing your build process or upgrading your plan

R2 Bucket Operations Fail​

Cannot create buckets or access bucket contents.

Cause: Naming conflicts, permissions issues, or trying to access objects via wrong API.

Solution:

  1. Bucket names must be globally unique across all Cloudflare accounts
  2. Use 3-63 lowercase characters, numbers, and hyphens (no underscores)
  3. Ensure your API token has R2 Edit permissions
  4. For object operations (upload/download), you must use S3-compatible APIs, not the REST API
  5. Generate temporary credentials using Generate R2 Credentials tool
  6. Use AWS SDK or S3-compatible tools with the R2 endpoint: https://<account-id>.r2.cloudflarestorage.com

KV Operations Return Empty or Stale Data​

KV reads return unexpected or missing data.

Cause: KV is eventually consistent, or keys have expired.

Solution:

  1. KV has eventual consistency - writes may take up to 60 seconds to propagate globally
  2. Check if keys have expired (if TTL was set during write)
  3. Verify you're using the correct namespace ID
  4. List keys to confirm the key exists before reading
  5. For read-after-write consistency, consider using Durable Objects instead
  6. Cache headers on KV reads may affect freshness in some contexts

Additional Resources​