Authentication

Configure authentication for the Cloudflare TypeScript SDK

Authentication

The Cloudflare TypeScript SDK supports multiple authentication methods to access the Cloudflare API. Choose the method that best fits your use case.

API token (recommended)

API tokens are the preferred and most secure way to authenticate with the Cloudflare API. Tokens can be scoped to specific permissions and resources.

Creating an API token

1. Access the Cloudflare Dashboard

   Visit the Cloudflare Dashboard and navigate to My Profile > API Tokens.

2. Create a new token

   Click Create Token and either:

   • Select a pre-configured template (recommended for common use cases)
   • Create a custom token with specific permissions
3. Configure permissions

   Select the permissions and resources your token needs access to. Follow the principle of least privilege.

4. Save your token

   Copy the generated token immediately. You won’t be able to view it again.

Learn more about creating API tokens

Using an API token

Set the token using the apiToken option or the CLOUDFLARE_API_TOKEN environment variable:

Constructor option

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: 'your_api_token_here',
});

// .env file
CLOUDFLARE_API_TOKEN=your_api_token_here

import Cloudflare from 'cloudflare';

// Automatically reads CLOUDFLARE_API_TOKEN from environment
const client = new Cloudflare();

The SDK will automatically read the CLOUDFLARE_API_TOKEN environment variable if no apiToken is explicitly provided.

API key + email (legacy)

The API key and email combination is the previous authorization scheme. When possible, use API tokens instead for better security and granular permissions.

Finding your API key

1. Access your profile

   Go to My Profile > API Tokens in the Cloudflare Dashboard.

2. View Global API Key

   Scroll to the API Keys section and click View next to Global API Key.

3. Copy the key

   Enter your password to reveal and copy your Global API Key.

Using API key + email

Provide both apiKey and apiEmail options, or use environment variables:

Constructor options

import Cloudflare from 'cloudflare';

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

// .env file
CLOUDFLARE_API_KEY=your_api_key_here
CLOUDFLARE_EMAIL=[e-mail]

import Cloudflare from 'cloudflare';

// Automatically reads CLOUDFLARE_API_KEY and CLOUDFLARE_EMAIL
const client = new Cloudflare();

Global API Keys have full access to your account. Use API tokens with scoped permissions whenever possible.

User service key

User service keys are used for specific API endpoints, such as the Origin CA certificates API. This is a specialized authentication method for certificate management.

Finding your user service key

You can view or change your Origin CA key at: https://developers.cloudflare.com/fundamentals/api/get-started/ca-keys/#viewchange-your-origin-ca-keys

Using a user service key

Provide the userServiceKey option or use the CLOUDFLARE_API_USER_SERVICE_KEY environment variable:

Constructor option

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  userServiceKey: 'your_user_service_key_here',
});

// .env file
CLOUDFLARE_API_USER_SERVICE_KEY=your_user_service_key_here

import Cloudflare from 'cloudflare';

// Automatically reads CLOUDFLARE_API_USER_SERVICE_KEY
const client = new Cloudflare();

Authentication priority

When multiple authentication methods are configured, the SDK uses them in this order:

1. API key + email: If both apiKey and apiEmail are provided
2. API token: If apiToken is provided
3. User service key: If userServiceKey is provided

The SDK will automatically include the appropriate headers based on the authentication method:

• API token: Authorization: Bearer <token>
• API key + email: X-Auth-Key: <key> and X-Auth-Email: <email>
• User service key: X-Auth-User-Service-Key: <key>

Environment variables reference

All supported environment variables for authentication:

Environment Variable	Description	Auth Method
CLOUDFLARE_API_TOKEN	Your API token	API Token (recommended)
CLOUDFLARE_API_KEY	Your Global API Key	API Key + Email (legacy)
CLOUDFLARE_EMAIL	Your Cloudflare account email	API Key + Email (legacy)
CLOUDFLARE_API_USER_SERVICE_KEY	Your user service key	User Service Key

Security best practices

1. Use API tokens instead of API keys

   API tokens can be scoped to specific permissions and are more secure than Global API Keys.

2. Never commit credentials to version control

   Always use environment variables or a secrets management system. Add .env to your .gitignore.

3. Rotate credentials regularly

   Periodically rotate your API tokens and keys to minimize security risks.

4. Use scoped permissions

   When creating API tokens, only grant the minimum permissions required for your use case.

5. Monitor token usage

   Regularly review token usage in the Cloudflare Dashboard and revoke unused tokens.

Common errors

Authentication required

If you see this error, ensure you’ve provided valid credentials:

Error: Could not resolve authentication method. Expected one of apiEmail, 
apiKey, apiToken or userServiceKey to be set.

Solution: Provide at least one valid authentication method through constructor options or environment variables.

Invalid credentials

If you receive a 401 AuthenticationError, your credentials may be incorrect or expired:

try {
  const zones = await client.zones.list();
} catch (err) {
  if (err instanceof Cloudflare.AuthenticationError) {
    console.error('Invalid credentials:', err.message);
    // Check your API token/key and try again
  }
}

Solution: Verify your credentials are correct and haven’t expired. Generate a new token if needed.

Next steps

Quick start

Make your first authenticated API call

API Reference

Explore available API endpoints