From 70d934abd91cfa8f8444e0651ac97012c1d0edcf Mon Sep 17 00:00:00 2001
From: Musa Jundi <musa@cloudflare.com>
Date: Thu, 30 Apr 2026 01:39:37 -0500
Subject: [PATCH] docs: add Authentication section to README

Document the supported authentication methods (API Token, API Key +
Email) with code examples, environment variable mappings, and a summary
table.
---
 README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/README.md b/README.md
index 6b81dde75a4..6c6ecaf639c 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,45 @@ The REST API documentation can be found on [developers.cloudflare.com](https://d
 pip install --pre cloudflare
 ```
 
+## Authentication
+
+The SDK supports multiple authentication methods. Each can be provided as a constructor argument or read automatically from an environment variable.
+
+### API Token (recommended)
+
+[API tokens](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) are scoped to specific permissions and are the recommended way to authenticate.
+
+```python
+from cloudflare import Cloudflare
+
+client = Cloudflare(api_token="your-api-token")
+
+# Or set the CLOUDFLARE_API_TOKEN environment variable and omit the argument:
+client = Cloudflare()
+```
+
+### API Key + Email
+
+The [Global API Key](https://developers.cloudflare.com/fundamentals/api/get-started/keys/) authenticates using a key and email pair. Both must be provided together.
+
+```python
+from cloudflare import Cloudflare
+
+client = Cloudflare(
+    api_key="your-global-api-key",
+    api_email="user@example.com",
+)
+
+# Or set CLOUDFLARE_API_KEY and CLOUDFLARE_EMAIL environment variables:
+client = Cloudflare()
+```
+
+| Parameter | Environment variable | Header sent |
+|-----------|---------------------|-------------|
+| `api_token` | `CLOUDFLARE_API_TOKEN` | `Authorization: Bearer <token>` |
+| `api_key` | `CLOUDFLARE_API_KEY` | `X-Auth-Key: <key>` |
+| `api_email` | `CLOUDFLARE_EMAIL` | `X-Auth-Email: <email>` |
+
 ## Usage
 
 The full API of this library can be found in [api.md](api.md).