Cloudflare API Tokens: Create and Manage -- Complete Guide

In this tutorial, you will learn how to create Cloudflare API tokens with granular permissions, use them for automated deployments and CI/CD pipelines, and manage token rotation and revocation for security.

Why API Tokens Matter

Cloudflare offers two authentication methods for its API: API keys (global, tied to your user account) and API tokens (scoped, per-purpose credentials). API keys have full access to everything in your account, making them dangerous if leaked. API tokens are the modern, security-recommended approach -- each token has a specific set of permissions scoped to specific resources, so a leaked token can only do what you explicitly allowed. This is critical when integrating Cloudflare with third-party services, CI/CD pipelines, infrastructure-as-code tools like Terraform, or automation scripts. Cloudflare API tokens support over 100 permission combinations across DNS, Workers, Pages, KV, R2, D1, Zero Trust, and every other Cloudflare service. By using scoped tokens instead of global API keys, you follow the principle of Least Privilege and reduce the Blast Radius of any credential exposure. For deployments involving Cloudflare Workers and Cloudflare Pages, API tokens are required for programmatic management.

Real-world use: A CI/CD pipeline needs to deploy Cloudflare Workers and purge cache after deployment. Instead of sharing a global API key that can also modify billing and delete zones, you create a token with Workers:Write and Cache:Purge permissions scoped to a single zone. If this token leaks, the attacker can only deploy Workers and purge cache on that one zone.

API Token Architecture

flowchart LR
    U[User] --> D[Cloudflare Dashboard]
    D --> T[Create Token]
    T --> W[Workers Token]
    T --> D2[DNS Token]
    T --> P[Pages Token]
    W --> CI["CI/CD Pipeline"]
    D2 --> TF[Terraform]
    P --> GH[GitHub Actions]
    style D fill:#f90,color:#fff
    style T fill:#f90,color:#fff

Creating an API Token

Navigate to the API Tokens section in your Cloudflare dashboard.

# Step 1: Go to API Tokens
# Cloudflare Dashboard > My Profile > API Tokens
# Click "Create Token"

# Step 2: Choose a template or start custom
# Pre-built templates:
# - Edit DNS (DNS:Write)
# - Workers and Pages Deploy (Workers:Write, Pages:Write)
# - Purge Cache (Cache:Purge)
# - Read All Resources (Read-only access)

# Step 3: Custom token configuration example
# Token Name: "Production DNS Manager"
# Permissions:
#   Zone > DNS > Edit
#   Zone > Zone > Read
# Zone Resources:
#   Include > Specific zone > example.com
# Client IP Address Filtering:
#   Allow > 203.0.113.0/24 (restrict to office IPs)
# TTL: Never expire (or set a specific end date)

# Expected result: A token that can only manage DNS
# records for example.com from the office network.

Using API Tokens with curl

API tokens are passed via the Authorization: Bearer header.

# List all DNS records for a zone using the token
curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

# Expected output:
# {
#   "success": true,
#   "result": [
#     { "type": "A", "name": "example.com", "content": "203.0.113.10" }
#   ]
# }

# Create a new DNS record
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "content": "203.0.113.10",
    "ttl": 120,
    "proxied": true
  }'

# Expected output:
# { "success": true, "result": { "id": "record_id", ... } }

Using API Tokens with Terraform

API tokens integrate natively with the Cloudflare Terraform provider for infrastructure-as-code workflows.

# providers.tf
terraform {
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 4.0"
    }
  }
}

provider "cloudflare" {
  api_token = var.cloudflare_api_token
}

# Set the token as an environment variable
export CLOUDFLARE_API_TOKEN="YOUR_API_TOKEN"

# Run Terraform
terraform plan
<a href="/devops/terraform/">Terraform</a> apply

Rotating and Revoking Tokens

Regular token rotation limits exposure from undetected leaks.

# To revoke a token immediately:
# Cloudflare Dashboard > My Profile > API Tokens
# Find the token > Click "Revoke"

# To rotate a token:
# 1. Create a new token with the same permissions
# 2. Update your applications to use the new token
# 3. Revoke the old token after confirming the new one works

Common Errors

Practice Questions

1. What is the difference between a Cloudflare API key and an API token in terms of security?
2. How do you restrict an API token to only work with DNS records for a specific domain?
3. How do you pass an API token when making requests via curl?

FAQ

{{< faq "Can API tokens be used with Cloudflare Wrangler CLI?">}} Yes. The Wrangler CLI supports API tokens via the <a href="/web-servers-hosting/cloudflare/">Cloudflare</a>_API_TOKEN environment variable or by configuring the token in your wrangler.toml file. Using a scoped token with Wrangler is recommended over using a global API key for automated deployments.{{< /faq >}}

Summary

Cloudflare API tokens provide granular, scoped authentication for programmatic access to Cloudflare services. Unlike global API keys, tokens follow the principle of Least Privilege by restricting permissions to specific resources and actions. Use tokens for CI/CD pipelines, Terraform deployments, and third-party integrations with regular rotation for security.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro -- security-first tools for the modern web.