The Cloudflare SDK provides flexible configuration options for customizing client behavior, authentication, network settings, and more.
Basic initialization
Create a new Cloudflare client with your API token:
import Cloudflare from 'cloudflare';
const client = new Cloudflare({
apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});
The SDK automatically reads the CLOUDFLARE_API_TOKEN environment variable if no apiToken is provided.
Authentication methods
The SDK supports multiple authentication methods:
API Token (Recommended)
Global API Key
User Service Key
const client = new Cloudflare({
apiToken: 'your-api-token',
});
const client = new Cloudflare({
apiEmail: '[email protected]',
apiKey: 'your-global-api-key',
});
Global API keys grant full account access. Use API tokens instead when possible.
const client = new Cloudflare({
userServiceKey: 'your-service-key',
});
Configuration options
The ClientOptions interface provides comprehensive configuration:
API token for authentication (reads from CLOUDFLARE_API_TOKEN by default)
Global API key for legacy authentication
Email address used with Global API key
Service key for Origin CA certificates API
baseURL
string
default:"https://api.cloudflare.com/client/v4"
Override the default base URL for the API
Define the API version to target for requests (e.g., “2025-01-01”)
Maximum time in milliseconds to wait for a response (default: 1 minute)
Maximum number of retry attempts for failed requests
Custom HTTP(S) agent for managing connections
Custom fetch function implementation
Default headers included with every request
Default query parameters included with every request
Custom base URL
Override the API endpoint for testing or alternative environments:
const client = new Cloudflare({
baseURL: 'https://api.example.com/v2/',
apiToken: process.env['CLOUDFLARE_API_TOKEN'],
});
CLOUDFLARE_BASE_URL environment variable:
export CLOUDFLARE_BASE_URL=https://api.example.com/v2/
HTTP agent configuration
Configure a custom HTTP agent for proxy support or connection pooling:
import http from 'http';
import { HttpsProxyAgent } from 'https-proxy-agent';
import Cloudflare from 'cloudflare';
// Configure the default for all requests
const client = new Cloudflare({
httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),
});
// Override per-request
await client.zones.delete(
{ zone_id: '023e105f4ecef8ad9ca31a8372d0c353' },
{
httpAgent: new http.Agent({ keepAlive: false }),
},
);
By default, the SDK uses a stable agent to reuse TCP connections, eliminating handshakes and improving performance.
Custom fetch implementation
Provide a custom fetch function for logging, middleware, or alternative implementations:
import { fetch } from 'undici';
import Cloudflare from 'cloudflare';
const client = new Cloudflare({
fetch: async (url: RequestInfo, init?: RequestInit): Promise<Response> => {
console.log('About to make a request', url, init);
const response = await fetch(url, init);
console.log('Got response', response);
return response;
},
});
Fetch shims
The SDK uses node-fetch in Node.js by default. To use the global web-standards fetch:
// Use global web fetch (e.g., in NextJS or with --experimental-fetch)
import 'cloudflare/shims/web';
import Cloudflare from 'cloudflare';
import 'cloudflare/shims/node';
import Cloudflare from 'cloudflare';
Default headers and query parameters
Add custom headers or query parameters to all requests:
const client = new Cloudflare({
apiToken: process.env['CLOUDFLARE_API_TOKEN'],
defaultHeaders: {
'X-Custom-Header': 'custom-value',
},
defaultQuery: {
debug: 'true',
},
});
undefined or null.
Debug logging
Enable automatic request/response logging:
DEBUG=true node your-script.js
Debug logging is intended for development only and may change without notice.