Table of Contents

API Token Permissions

This guide covers the API token permissions required for each SDK feature.

Overview

Cloudflare uses a permission-based system for API tokens. To adhere to the principle of least privilege, create API tokens with only the required scopes for your use case.

Permission Reference

Permission Group Scope Level Typical Uses
Workers R2 Storage Account Write Create/delete R2 buckets, manage domains
Workers R2 Storage Account Read List buckets and read configurations
Account Firewall Access Rules Account Write Manage IP Access Rules at account level
Account Firewall Access Rules Account Read Audit firewall rules at account level
Firewall Services Zone Write Manage IP Access Rules at zone level
Account Rulesets Account Write Deploy WAF custom rulesets at account level
Account Rulesets Account Read List WAF rulesets at account level
Zone WAF Zone Write Deploy WAF custom rulesets at zone level
Zone WAF Zone Read List WAF rulesets at zone level
DNS Zone Write Automate DNS changes, bulk import/export
DNS Zone Read List and verify DNS state
Cache Purge Zone Purge Purge cache via API
SSL and Certificates Zone Write Manage client certificates, SaaS hostnames
SSL and Certificates Zone Read Monitor certificate status
Account Analytics Account Read Query R2 usage via GraphQL

R2 Credentials

Note

The R2 S3-compatible client (IR2Client) uses separate R2 credentials (Access Key ID and Secret), not API tokens. These credentials are created in the Cloudflare dashboard under R2 > Manage R2 API Tokens.

Permissions by Feature

Zones API

FeaturePermissionLevel
DNS RecordsDNSZone: Write
DNS Import/ExportDNSZone: Write
Cache PurgeCache PurgeZone: Purge
Zone DetailsZoneZone: Read
Custom HostnamesSSL and CertificatesZone: Write

Zone Security

FeaturePermissionLevel
IP Access RulesFirewall ServicesZone: Write
Zone LockdownFirewall ServicesZone: Write
User-Agent RulesFirewall ServicesZone: Write
WAF RulesetsZone WAFZone: Write

Accounts API

FeaturePermissionLevel
R2 BucketsWorkers R2 StorageAccount: Write
R2 Custom DomainsWorkers R2 StorageAccount: Write
R2 CORS ConfigurationWorkers R2 StorageAccount: Write
R2 Lifecycle PoliciesWorkers R2 StorageAccount: Write

Workers KV

FeaturePermissionLevel
KV Namespaces (read)Workers KV StorageAccount: Read
KV Namespaces (write)Workers KV StorageAccount: Write
KV Keys (read)Workers KV StorageAccount: Read
KV Values (read/write)Workers KV StorageAccount: Write
KV Bulk OperationsWorkers KV StorageAccount: Write

D1 Databases

FeaturePermissionLevel
D1 Databases (read)D1Account: Read
D1 Databases (write)D1Account: Write
D1 QueriesD1Account: Write
D1 Export/ImportD1Account: Write

Account Security

FeaturePermissionLevel
IP Access RulesAccount Firewall Access RulesAccount: Write
WAF RulesetsAccount RulesetsAccount: Write

Analytics

FeaturePermissionLevel
GraphQL QueriesAccount AnalyticsAccount: Read

Creating an API Token

  1. Log in to the Cloudflare Dashboard
  2. Go to My Profile > API Tokens
  3. Click Create Token
  4. Either use a template or create a custom token
  5. Select only the permissions you need
  6. Optionally restrict to specific zones or accounts
  7. Copy the token (it won't be shown again)

Best Practices

  • Least Privilege: Only grant permissions that are actually needed
  • Scope Restriction: Limit tokens to specific zones or accounts when possible
  • Token Rotation: Rotate tokens periodically for security
  • Separate Tokens: Use different tokens for different applications or environments
  • Never Commit: Store tokens in environment variables or secret managers, never in source control
Edit this page