Client configuration

Learn how to initialize and configure the Cloudflare SDK client

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)

const client = new Cloudflare({
  apiToken: 'your-api-token',
});

API tokens provide granular permissions and are the recommended authentication method. Create a token.

Global API Key

const client = new Cloudflare({
  apiEmail: '[e-mail]',
  apiKey: 'your-global-api-key',
});

Global API keys grant full account access. Use API tokens instead when possible.

User Service Key

const client = new Cloudflare({
  userServiceKey: 'your-service-key',
});

Used for interacting with Origin CA certificates. View/change your key.

Configuration options

The ClientOptions interface provides comprehensive configuration:

apiToken · string

API token for authentication (reads from CLOUDFLARE_API_TOKEN by default)

apiKey · string

Global API key for legacy authentication

apiEmail · string

Email address used with Global API key

userServiceKey · string

Service key for Origin CA certificates API

baseURL · string · default: "https://api.cloudflare.com/client/v4"

Override the default base URL for the API

apiVersion · string

Define the API version to target for requests (e.g., “2025-01-01”)

timeout · number · default: "60000"

Maximum time in milliseconds to wait for a response (default: 1 minute)

maxRetries · number · default: "2"

Maximum number of retry attempts for failed requests

httpAgent · Agent

Custom HTTP(S) agent for managing connections

fetch · Fetch

Custom fetch function implementation

defaultHeaders · Headers

Default headers included with every request

defaultQuery · DefaultQuery

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'],
});

You can also use the 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';

To explicitly use Node.js polyfills:

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',
  },
});

You can remove default headers in individual requests by setting them to 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.