Cloudflare API Authentication: Methods & Security (2026)

Authentication overview

Cloudflare API authentication governs how programmatic requests verify their identity and authorization to interact with Cloudflare's infrastructure. This process ensures that only authenticated and authorized entities can manage resources such as DNS records, security configurations, WAF rules, and CDN settings. The Cloudflare API supports two primary methods for authentication: API Tokens and the Global API Key, each offering distinct security and flexibility profiles Cloudflare API authentication documentation. Proper selection and management of these credentials are fundamental to maintaining the security and integrity of your Cloudflare-protected assets.

For most use cases, particularly those requiring fine-grained control and adherence to the principle of least privilege, API Tokens are the recommended approach. They allow developers to create credentials with specific permissions, limiting potential damage if a token is compromised. The Global API Key, while offering full account access, is generally reserved for legacy integrations or specific setup procedures where broad permissions are explicitly required and its security implications are fully understood. All interactions with the Cloudflare API must occur over HTTPS to protect credentials and data in transit, aligning with industry standards for secure API communication HTTP/1.1 RFC 7230 specification.

Supported authentication methods

Cloudflare API supports the following authentication methods, each designed for different levels of access and security requirements:

API Tokens

API Tokens are the preferred method for authenticating with the Cloudflare API. They follow a Bearer Token model, where the token is included in the Authorization header of HTTP requests. Key features include:

• Granular Permissions: Tokens can be configured with specific read and write permissions for particular resources (e.g., DNS, Workers, WAF) and zones (domains) Cloudflare API token creation guide.
• IP Address Filtering: You can restrict a token's usability to specific IP addresses or CIDR ranges.
• Expiration Dates: Tokens can be set to expire automatically after a certain period.
• Auditable Actions: Actions performed with an API token are logged and visible in the Cloudflare Dashboard, providing better traceability.

Global API Key

The Global API Key is an account-level credential that provides full administrative access to all Cloudflare services associated with your account. It is usually found in your Cloudflare user profile and is used in conjunction with your Cloudflare account email in the request headers.

• Full Account Access: Grants complete control over all zones and settings under your Cloudflare account.
• Uses X-Auth-Key and X-Auth-Email: Authenticates by sending the API key in the X-Auth-Key header and your Cloudflare account email in the X-Auth-Email header.
• Security Risk: Due to its extensive permissions, compromise of the Global API Key can lead to significant security breaches. Its use is strongly discouraged for automated processes or third-party integrations where granular control is possible with API Tokens.

Getting your credentials

Both API Tokens and the Global API Key are managed through the Cloudflare Dashboard.

Creating an API Token

1. Log in to your Cloudflare Dashboard API Tokens page.
2. Navigate to My Profile > API Tokens.
3. Click Create Token.
4. Choose from a template or create a custom token. For custom tokens, define the permissions (e.g., Zone > DNS > Edit) and specify the zones the token applies to.
5. (Optional) Add IP address filtering and set an expiration date.
6. Review the summary and click Create Token.
7. Copy the token value immediately. It will only be shown once.

Retrieving your Global API Key

1. Log in to your Cloudflare Dashboard Profile page.
2. Navigate to My Profile > API Tokens.
3. Scroll down to the Global API Key section.
4. Click View next to the Global API Key. You may be prompted to re-enter your password for security verification.
5. Copy the displayed key.

Authenticated request example

Here are examples of how to make an authenticated request using both an API Token and the Global API Key with curl, a common command-line tool for making HTTP requests.

Using an API Token

When using an API Token, include it in the Authorization header with the Bearer scheme.

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json"

This example retrieves a list of API tokens associated with your account, assuming the YOUR_API_TOKEN has the necessary permissions (e.g., User > API Tokens > Read).

Using the Global API Key

When using the Global API Key, include your API key in the X-Auth-Key header and your Cloudflare account email in the X-Auth-Email header.

curl -X GET "https://api.cloudflare.com/client/v4/user" \
     -H "X-Auth-Email: YOUR_CLOUDFLARE_EMAIL" \
     -H "X-Auth-Key: YOUR_GLOBAL_API_KEY" \
     -H "Content-Type: application/json"

This example retrieves information about your Cloudflare user account. Replace YOUR_CLOUDFLARE_EMAIL with your actual Cloudflare account email and YOUR_GLOBAL_API_KEY with your Global API Key.

Security best practices

Adhering to security best practices is crucial when handling Cloudflare API credentials to prevent unauthorized access and potential service disruptions.

• Prefer API Tokens over Global API Key: Always use API Tokens for new integrations and automated tasks. Configure tokens with the minimum necessary permissions (principle of least privilege) to limit the impact of a potential compromise.
• Restrict Token Permissions: When creating an API Token, carefully define the scope of its access. Specify only the zones and API resources required for its intended function. For example, if a token only needs to update DNS records for a specific domain, grant it only Zone > DNS > Edit permissions for that single zone.
• Implement IP Filtering: For API Tokens, restrict access to a specific range of IP addresses from which requests are expected to originate. This adds an extra layer of security, making it harder for attackers to use a stolen token from an unauthorized location.
• Set Expiration Dates: Configure API Tokens with expiration dates to ensure they are automatically revoked after a certain period. For long-running processes, consider implementing a rotation strategy for tokens.
• Store Credentials Securely: Never hardcode API keys or tokens directly into source code. Use environment variables, secret management services (e.g., AWS Secrets Manager, Google Secret Manager), or secure configuration files. Access controls on these storage mechanisms should be strictly enforced.
• Monitor API Logs: Regularly review Cloudflare API logs in your dashboard for unusual activity, failed authentication attempts, or unexpected resource access. This can help detect and respond to potential security incidents promptly.
• Rotate Credentials Periodically: Even with strong security measures, it is good practice to periodically rotate API tokens and, if absolutely necessary, the Global API Key. This minimizes the window of opportunity for a compromised credential to be exploited.
• Use HTTPS: All communication with the Cloudflare API must be over HTTPS to encrypt data in transit, protecting your credentials and sensitive information from eavesdropping.
• Enable Multi-Factor Authentication (MFA) on Cloudflare Account: Protecting your Cloudflare account with MFA adds a critical layer of security, preventing unauthorized access to your dashboard where API keys and tokens are managed Cloudflare MFA setup guide.
• Avoid Sharing Credentials: API keys and tokens are personal credentials. They should never be shared directly with other users or teams. Instead, create separate tokens with appropriate permissions for each user or application.