From 061311611d8e13fa5dc9a67e85a7f7e6c5e747f0 Mon Sep 17 00:00:00 2001
From: "J.Jason" <130959319+JJasonSun@users.noreply.github.com>
Date: Tue, 15 Sep 2026 14:29:35 +0800
Subject: [PATCH 1/2] docs: clarify API key placeholders and safe diagnostic
 sharing

---
 CHANGELOG.md    |  4 ++++
 CONTRIBUTING.md |  6 +++++-
 README.md       | 34 +++++++++++++++++++++++++++++++++-
 3 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 52a1a81..d40d7f0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+### Changed
+
+- Clarify placeholder API keys and redaction of credentials and private call data in SDK documentation.
+
 ## [0.7.1] - 2026-09-04
 
 ### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f98bed5..b10d3f1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,8 +15,12 @@ fresh wheel and source-distribution installs.
 
 ## Local examples
 
+Replace the sample credentials with your own key before running. Read
+[API keys and diagnostic output](./README.md#api-keys-and-diagnostic-output)
+before sharing example output.
+
 ```bash
-export CALLE_API_KEY="calle_test_key"
+export CALLE_API_KEY="iams_live_example"
 export CALLE_BASE_URL="https://api.heycall-e.com"
 export CALLE_EXAMPLE_PHONE="+14155550100"
 uv run python examples/create_and_wait.py
diff --git a/README.md b/README.md
index eb6241f..4512ef4 100644
--- a/README.md
+++ b/README.md
@@ -68,12 +68,44 @@ with CalleClient(api_key=os.environ["CALLE_API_KEY"]) as client:
     call = client.calls.get("call_123")
 ```
 
+## API keys and diagnostic output
+
+Use the complete API key issued by the [CALL-E dashboard](https://dashboard.heycall-e.com/account/api-keys).
+`iams_live_example` and the fallback keys in example scripts are non-working
+placeholders. Replace them with your own key; do not derive key validation or
+redaction patterns from a sample prefix.
+
+Before logging or sharing diagnostics:
+
+- Prefer a small set of fields such as SDK version, HTTP status, and error
+  code over dumping a full request, response, or error object.
+- Remove the entire `Authorization` header and configured secret values.
+  Matching one key prefix is not sufficient.
+- Review phone fields and free text, including `task`, transcripts, summaries,
+  evidence, custom results, metadata, and error details. The SDK preserves the
+  returned task text, which may contain a phone number or other private data.
+  Dashboard masking does not redact SDK output or raw API responses.
+
+For example, a manually redacted response excerpt for sharing can omit all
+other fields and replace both the task and recipient phone:
+
+```json
+{
+  "status": "completed",
+  "task": "[REDACTED]",
+  "recipients": [{"phones": ["[REDACTED]"]}]
+}
+```
+
+This is a diagnostic excerpt, not a create request. Inspect the final text
+before publishing it; these replacements are not a general-purpose PII filter.
+
 ## Examples
 
 Set the API key before running call examples:
 
 ```bash
-export CALLE_API_KEY="calle_test_key"
+export CALLE_API_KEY="iams_live_example"
 export CALLE_BASE_URL="https://api.heycall-e.com"
 export CALLE_EXAMPLE_PHONE="+14155550100"
 ```

From 0d07a8c9a99a85bd97fe7a116b11cf3aeefe4f81 Mon Sep 17 00:00:00 2001
From: "J.Jason" <130959319+JJasonSun@users.noreply.github.com>
Date: Tue, 15 Sep 2026 17:28:40 +0800
Subject: [PATCH 2/2] docs: use explicit API key placeholders

---
 CONTRIBUTING.md | 2 +-
 README.md       | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b10d3f1..19bed86 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,7 +20,7 @@ Replace the sample credentials with your own key before running. Read
 before sharing example output.
 
 ```bash
-export CALLE_API_KEY="iams_live_example"
+export CALLE_API_KEY="<YOUR_CALLE_API_KEY>"
 export CALLE_BASE_URL="https://api.heycall-e.com"
 export CALLE_EXAMPLE_PHONE="+14155550100"
 uv run python examples/create_and_wait.py
diff --git a/README.md b/README.md
index 4512ef4..f73f2b8 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,7 @@ with CalleClient(api_key=os.environ["CALLE_API_KEY"]) as client:
 ## API keys and diagnostic output
 
 Use the complete API key issued by the [CALL-E dashboard](https://dashboard.heycall-e.com/account/api-keys).
-`iams_live_example` and the fallback keys in example scripts are non-working
+`<YOUR_CALLE_API_KEY>` and the fallback keys in example scripts are non-working
 placeholders. Replace them with your own key; do not derive key validation or
 redaction patterns from a sample prefix.
 
@@ -105,7 +105,7 @@ before publishing it; these replacements are not a general-purpose PII filter.
 Set the API key before running call examples:
 
 ```bash
-export CALLE_API_KEY="iams_live_example"
+export CALLE_API_KEY="<YOUR_CALLE_API_KEY>"
 export CALLE_BASE_URL="https://api.heycall-e.com"
 export CALLE_EXAMPLE_PHONE="+14155550100"
 ```