Cloudflare Authentication: API Keys, Tokens, and OAuth (2026)

Authentication overview

Cloudflare provides several methods for authenticating requests to its API, allowing developers and administrators to programmatically manage their Cloudflare resources. These methods range from highly granular API tokens to broader global API keys and OAuth 2.0 for delegated authorization. The choice of authentication method depends on the use case, required scope of access, and security considerations.

The Cloudflare API enables interaction with various services, including DNS management, WAF configuration, CDN settings, and Cloudflare Workers deployment. Proper authentication ensures that only authorized entities can perform actions on your Cloudflare account and its associated assets. Cloudflare emphasizes the use of API tokens due to their flexibility and enhanced security features compared to the legacy global API key.

Supported authentication methods

Cloudflare supports three primary authentication methods for its API:

• API Tokens: These are the recommended method for most API interactions. API tokens offer granular control over permissions, allowing users to define specific access rights (e.g., read-only access to DNS records for a particular zone). They can also be restricted by IP address and time, enhancing security by limiting their usability if compromised. API tokens are designed to adhere to the principle of least privilege, minimizing the potential impact of a token breach.
• Global API Key: This is a legacy authentication method that grants full administrative access to your entire Cloudflare account. It is equivalent to your account password and should be used with extreme caution, ideally only for initial setup or in scenarios where API tokens cannot fulfill requirements. Cloudflare generally advises against using the global API key for routine API operations due to its broad permissions.
• OAuth 2.0: This protocol is used for delegated authorization, allowing third-party applications to access Cloudflare resources on behalf of a user without requiring the user's Cloudflare credentials directly. OAuth 2.0 is suitable for integrations where an application needs to interact with a user's Cloudflare account (e.g., a SaaS platform offering Cloudflare integration). It provides a secure and standardized way to manage permissions for external services. For more details on the OAuth 2.0 framework, refer to the OAuth 2.0 specification.

The following table summarizes Cloudflare's authentication methods:

Getting your credentials

Accessing and generating authentication credentials for Cloudflare typically involves navigating the Cloudflare Dashboard:

API Tokens

1. Log in to your Cloudflare Dashboard.
2. Navigate to My Profile > API Tokens.
3. Click Create Token.
4. Choose from a template or create a custom token. For custom tokens, you define specific permissions (e.g., Zone:DNS:Edit) and resource access (e.g., specific zones or all zones). You can also add IP address filtering and a token expiration date.
5. Review the token summary and click Create Token.
6. Copy the token value immediately, as it will not be displayed again.

For detailed instructions on creating and managing API tokens, consult the Cloudflare API Token documentation.

Global API Key

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

Remember that using the Global API Key grants full access to your account. Cloudflare strongly recommends using API Tokens instead for most use cases, as explained in their API Keys documentation.

OAuth 2.0

To use OAuth 2.0, you must register your application with Cloudflare. This process typically involves:

1. Log in to your Cloudflare Dashboard.
2. Navigate to My Profile > API Tokens > OAuth Clients (or Developers > API Clients, depending on dashboard version).
3. Register a new OAuth application, providing details such as the application name, homepage URL, and redirect URIs.
4. Upon registration, Cloudflare will provide a Client ID and Client Secret, which your application will use to initiate the OAuth flow.

The OAuth 2.0 flow involves redirecting users to Cloudflare for authorization, where they grant your application specific permissions. Upon successful authorization, Cloudflare redirects the user back to your application with an authorization code, which your application exchanges for an access token. This access token is then used to make API calls on behalf of the user. For a general understanding of the OAuth 2.0 authorization code grant flow, refer to the IETF RFC 6749 section on Authorization Code Grant.

Authenticated request example

The following example demonstrates how to make an authenticated request to the Cloudflare API using an API Token to list zones associated with your account. This example uses cURL, a common command-line tool for making HTTP requests.

curl -X GET "https://api.cloudflare.com/client/v4/zones"
     -H "Authorization: Bearer <YOUR_API_TOKEN>"
     -H "Content-Type: application/json"

In this example:

• -X GET specifies the HTTP method.
• "https://api.cloudflare.com/client/v4/zones" is the API endpoint to list zones.
• -H "Authorization: Bearer <YOUR_API_TOKEN>" is the header containing your API Token. Replace <YOUR_API_TOKEN> with your actual token.
• -H "Content-Type: application/json" specifies the content type of the request.

When using the Global API Key, the authentication headers would be different:

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

Here, you replace <YOUR_CLOUDFLARE_EMAIL> with the email associated with your Cloudflare account and <YOUR_GLOBAL_API_KEY> with your Global API Key.

Cloudflare also provides official SDKs for various programming languages, including Go, JavaScript, Python, PHP, Ruby, Java, and C#. These SDKs abstract away the details of HTTP requests and authentication, simplifying API interactions within your applications.

Security best practices

Adhering to security best practices is crucial when managing Cloudflare API credentials:

• Use API Tokens: Always prioritize API Tokens over the Global API Key. API tokens offer granular permissions, allowing you to grant only the necessary access for a specific task.
• Least Privilege: Apply the principle of least privilege. Configure API tokens with the minimum necessary permissions and resource access. For instance, if an application only needs to read DNS records for a single zone, do not grant it full account access or write permissions.
• IP Address Filtering: When creating API tokens, restrict their use to specific IP addresses or IP ranges whenever possible. This mitigates the risk of unauthorized access even if the token is compromised.
• Expiration Dates: Set expiration dates for API tokens, especially for temporary or short-lived integrations. This ensures that even if a token is forgotten or not explicitly revoked, its validity will eventually expire.
• Secure Storage: Never hardcode API keys or tokens directly into your application's source code. Use environment variables, secure configuration files, or dedicated secret management services (e.g., AWS Secrets Manager, Google Secret Manager, Azure Key Vault) to store credentials. For guidance on secure credential storage, refer to general security recommendations like those from Google Cloud Secret Manager best practices.
• Regular Rotation: Rotate API tokens and keys periodically. This practice limits the window of opportunity for attackers to use compromised credentials.
• Monitoring and Auditing: Regularly monitor API activity logs within your Cloudflare Dashboard to detect any unusual or unauthorized access patterns. Cloudflare provides audit logs that can track API calls made to your account.
• Revocation: Immediately revoke any compromised or no longer needed API tokens or keys from the Cloudflare Dashboard.
• Two-Factor Authentication (2FA): Enable 2FA on your Cloudflare account to protect access to the dashboard where credentials are managed.