Skip to main content

​
Authentication

The Cloudflare TypeScript SDK supports multiple authentication methods to access the Cloudflare API. Choose the method that best fits your use case. 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: 
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: 'your_api_token_here',
});
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: 
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiKey: 'your_api_key_here',
  apiEmail: '[email protected]',
});
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: 
import Cloudflare from 'cloudflare';

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

​
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 VariableDescriptionAuth Method
CLOUDFLARE_API_TOKENYour API tokenAPI Token (recommended)
CLOUDFLARE_API_KEYYour Global API KeyAPI Key + Email (legacy)
CLOUDFLARE_EMAILYour Cloudflare account emailAPI Key + Email (legacy)
CLOUDFLARE_API_USER_SERVICE_KEYYour user service keyUser 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

Build docs developers (and LLMs) love

Get started for freeTalk to us