Three non-negotiable rules CORE
Secrets handling is the part of Module 9 where the Core Book is shortest and the Recipe Book is longest. The principle is small — three rules, stated below — and the execution is many specific commands and console clicks, which is why this lesson’s tag mix is heavier on recipe than any other in the module. Learn the three rules so well you can recite them without looking, then turn the rest of the lesson into muscle memory.
Rule 1 — No secret in a conversation, ever. A secret is any string whose disclosure would let someone else act as you against a service: API keys, OAuth tokens, session cookies, passwords, database URLs with embedded passwords, private SSH keys, signing keys for any package you publish. Ever means: not in a Claude Code CLI prompt, not in a Cowork-tab chat, not in an email to yourself, not in a skill committed to git, not in a scheduled-task definition, not in a system prompt pasted for “debugging,” not in a screenshot you took to “remember the value,” not in a terminal transcript, not in the body of a bug report filed to a vendor. Every one of these is a place a secret has been leaked from by a student who “just needed it to debug something quickly.” The rule has to be categorical because the exceptions are where the leaks come from.
Rule 2 — Every key has a scope and a cap. A key that can do everything is a key that, when leaked, does everything. The shape of this rule:
- Scope — the set of actions the key is allowed to take. Your cloud-provider key should be scoped to the projects it actually needs (most providers call these “workspaces” or “projects”). If your provider supports granular permissions, further scope to the minimum set of capabilities the key needs — “use models, read usage data” is usually enough; “modify billing, create additional keys” usually is not.
- Cap — the dollar amount the key can spend in a billing period before the provider refuses more requests. Set this at a number you would notice on your next credit-card statement but could survive if it were spent unexpectedly. Most students land in the $20–$100/month range; the number matters less than the fact that there is a hard stop.
A key without a scope-and-cap is a foothold, not a tool. The cap is the second line of defense after the audience-equals-you rule, and it is a key knob in Module 9 after “no secret in a conversation.” Lesson 9.5 will revisit the cap in the context of monthly budgeting; this lesson is where the cap is set.
Rule 3 — A leaked key is rotated, not patched. If a secret has been seen anywhere it should not have been — a screenshot, a transcript, a chat, a commit, a stranger’s terminal, a support ticket — the correct response is: rotate the key, update the new one in the one place secrets live, and revoke the old one. Do not argue about whether the leak was “bad enough” to matter. Do not try to scrub the secret from the place it appeared (you cannot; screenshots propagate, transcripts are stored, commits are indexed). Do not tell yourself “probably nobody looked.” Rotate. The drill in Content Block 5 is what makes rotation fast enough to actually do instead of postpone.
These three rules compose. Rule 1 prevents most leaks from happening. Rule 2 bounds the blast radius when a leak happens anyway. Rule 3 closes the leak once discovered. A student with all three live has a secrets posture that survives the realistic mistakes of Adversary 1 (the careless self) from Lesson 9.1.
What “leaked” actually means CORE
Students who are new to secrets handling tend to underestimate leakage in two directions. They treat leaks as a binary (either “clearly leaked” or “clearly fine”) when most real leaks live in a grey zone, and they underestimate how many copies of a given secret exist in their setup at any moment.
Grey-zone leaks that count as “leaked” under the Module 9 rule:
- A secret pasted into a chat window “just for a second” to debug an error, then deleted. The transcript was stored before the deletion. The secret is leaked.
- A secret appearing in a screenshot the student took for their own reference. Every cloud backup, photo service, and synced folder now has a copy. The secret is leaked.
- A secret in a .env file that is in a repo with a .gitignore that almost covers it — until one commit where a mis-typed .gitignore let the file through. The secret is leaked. (Git’s history preserves it even after later removal.)
- A secret pasted into a bug report to a vendor, before the vendor’s triage team sanitizes it. The secret is leaked.
- A secret an agent “helpfully” echoed back in a response because the student had pasted a config file earlier in the conversation. The conversation transcript has it. The secret is leaked.
Leaks by multiplication. Count the copies of your main cloud-provider API key right now. In most students’ setups before Lesson 9.3, the honest count is five to ten: the provider’s console, the .env file on the laptop, the .env file on the spare laptop, the notes-app page where the student wrote it down “just in case,” the Claude Code CLI config, the Cowork-tab settings, at least one skill that read it, at least one scheduled task that needs it. Every copy is a place the secret can leak from. The Module 9 target is one copy — the OS-keychain or vault entry — with every consumer reading from that single source. The lesson is about collapsing five-to-ten down to one.
The realism move here is to assume that once a secret has been in a grey-zone leak, it has been leaked. This is not paranoia; it is calibration with how large-scale credential scraping actually works. Committed .env files get scraped within minutes on public repos; pasted credentials in bug reports get seen by support teams; screenshots land in synced cloud services that are themselves breached on a rolling basis. The cost of assuming a grey-zone leak is “a ten-minute rotation;” the cost of assuming it was fine and being wrong is “every dollar the attacker can spend before your cap stops them.” The asymmetry is why Rule 3 is categorical.
Secrets in a multi-agent pipeline CORE
The Module 8 callback for this lesson is short: in a multi-agent pipeline, secrets do not cross handoffs. A research subagent that needs a news-API key reads the key from the one secret store directly; it does not receive the key from the supervisor, and it does not write the key into the shared-state folder for downstream stages to read. The same is true on the Cowork-tab path: each scheduled task that needs a credential reads from the Cowork tab’s secrets pane or the OS keychain, not from the output of a previous task. Shared-state folders are public within the pipeline; secrets go elsewhere.
This matters because a pipeline that passes secrets through shared-state files turns every intermediate artifact into a credential leakage surface. An injection attack that successfully exfiltrates one of those files (or a student who accidentally commits one) has exfiltrated the secret, not just the data. The rule is to keep the two concerns physically separated: data flows through the pipeline folder; secrets do not.
Moving secrets out of conversations (Claude Code CLI and Cowork tab) RECIPE
| Tools | macOS Keychain · Windows Credential Manager · Linux secret-tool / pass · .env (dotenv convention) |
| Versions tested | macOS Keychain 15.x · Windows Credential Manager 11 · libsecret secret-tool current · pass 1.7.x · .env (tool-agnostic) |
| Last verified | 2026-04-20 |
| Next review | 2026-07-20 |
| Supported OSes | macOS, Windows, Linux (all three stores covered) |
This and the next two blocks are where the lesson gets hands-on. Follow the steps. Do not just read them.
The one secret store. Pick one of the following and commit to it for your setup:
- macOS: the Keychain (accessed via the security command-line tool, or the Keychain Access app). For environment-variable-style access, use a launchd wrapper or a shell function that reads from Keychain on-demand.
- Windows: the Credential Manager (accessed via PowerShell’s Get-Credential or the Windows-Native credential APIs), or the wincred npm package for Node-based tools.
- Linux: the Secret Service API (accessed via secret-tool, part of libsecret), or pass if you prefer a GPG-backed password store.
- Cross-platform fallback: a single .env file in a folder outside any git repo (for example, ~/.config/ai-architect-academy/secrets.env), with file permissions set to 600 (owner-read/write only). This is not as secure as the OS keychain but is far more secure than the typical Module 1–8 baseline.
The Recipe Book entry /recipe-book/env-and-secrets-basics/ (already in the course, updated for this lesson) carries the per-OS commands. The concept claim of this block is: you have one store. Every consumer reads from that store. Nothing else is allowed to hold a long-lived copy.
Inventory your current secrets
Open a scratch file and list every secret in your setup today. For each, write where it lives right now — all copies. Examples:
- ANTHROPIC_API_KEY → provider console; .env in ~/code/my-project/; pasted into Claude Code CLI config; pasted into the Cowork tab’s “API key” field; in the notes-app page titled “my keys.”
- OPENAI_API_KEY → provider console; .env (same file); Cowork-tab settings.
- GITHUB_TOKEN → provider console; ~/.netrc; a commit in an old branch (“ouch”); an email to myself from three months ago.
Collapse to one copy
For each secret, move it into your chosen one store, update every consumer (Claude Code CLI config, Cowork-tab settings, any scripts that read it) to read from the store instead of a local copy, delete the local copies everywhere you can, and — for the grey-zone places you cannot delete from (chat transcripts, synced notes, old git commits) — accept that the secret has been leaked and plan to rotate it in the rotation drill below. The Recipe Book entry /recipe-book/env-and-secrets-basics/ covers the “how do I point my shell / Claude Code CLI / Cowork tab at the keychain” step for each OS.
Concrete one-liners you will actually run. On macOS, add the key to the Keychain once:
# Store once in macOS Keychain (replace the value; do not paste it here in chat)
$security add-generic-password -a "$USER" -s ANTHROPIC_API_KEY -w
# Read it back on demand, e.g. from a shell function in ~/.zshrc
$security find-generic-password -a "$USER" -s ANTHROPIC_API_KEY -wOn Linux with libsecret:
# Store once
$secret-tool store --label="Anthropic API key" service anthropic key ANTHROPIC_API_KEY
# Read on demand
$secret-tool lookup service anthropic key ANTHROPIC_API_KEYThen export from the store at shell startup so the Claude Code CLI inherits it — a one-liner in your shell rc file:
# In ~/.zshrc or ~/.bashrc — reads keychain, exports env var for the session
$export ANTHROPIC_API_KEY="$(security find-generic-password -a "$USER" -s ANTHROPIC_API_KEY -w)"If you use the .env fallback instead, set permissions to 600 and keep the file outside every git repo:
$mkdir -p ~/.config/ai-architect-academy
$touch ~/.config/ai-architect-academy/secrets.env
$chmod 600 ~/.config/ai-architect-academy/secrets.envWhat this looks like on the Claude Code CLI path
A Claude Code CLI session that needs a cloud-provider key to call the API reads it from the environment the session was launched in. In practice: you set the env var from the keychain at shell startup (via a function in your .zshrc or .bashrc), and the CLI picks it up. You do not paste the key into any prompt or config file. If a Claude Code CLI skill needs a secret, the skill reads it from the environment, not from its own stored prompt.
What this looks like on the Cowork-tab path
The Cowork tab stores API keys in its own settings pane, and that storage is the authoritative location for the tab’s purposes — the settings pane is treated, for this lesson’s purposes, as an extension of the “one secret store.” You do not additionally paste the key into chat, plugin definitions, or skill prompts. The Cowork tab’s MCP connector pages are where per-MCP credentials live; those count as part of the one store as long as you treat them as authoritative for those connectors alone and do not duplicate them elsewhere.
What about the provider console itself?
The provider’s console is always a copy — it is where the key was generated. That is fine; the provider’s console is a trusted location for secrets created there. What you are collapsing is your own copies of that secret.
Scoping and capping the cloud-provider key RECIPE
| Tool | Anthropic Console (web) |
| Version tested | console as of 2026-04-20 |
| Last verified | 2026-04-20 |
| Next review | 2026-07-20 |
| Supported OSes | Web — any OS |
This is a high-impact five-minute action in Module 9 for most students.
Scoping
Open your cloud provider’s console. Find the key you use as your default (the one named in Module 2). Check whether the provider supports project-level or workspace-level scoping for keys. If yes, create a project named AI Architect Academy (or whatever name fits your convention), move your current usage into that project, generate a new key scoped only to that project, update the one secret store to point at the new key, and delete the old broader key. The old key’s blast radius (if leaked) just shrank from “everything you do with this provider” to “one project’s monthly cap.” Most major providers (Anthropic, OpenAI, Google) support this as of Module 9’s writing; the Recipe Book entry carries the current console path.
If the provider’s key permissions are granular (for example, you can create a key that can call inference endpoints but not create new keys), set the permissions to the minimum your agents need. Default principle: keys can call models and read their own usage; keys do not create other keys, modify billing, or access org-level settings. Any permission you add beyond that should have a written reason.
Capping
In the same console, find the billing or usage section. Look for “monthly cap,” “hard limit,” “budget cap,” or similar. Set it. Most providers expose two knobs: a soft alert threshold (they email you when usage crosses a percentage of the cap) and a hard cap (they refuse to serve more requests once the cap is hit). Set both. For a Module 9 student, typical numbers:
- Alert threshold: $10 for students still gauging their typical monthly spend; $30–$50 for students who already know they run closer to that.
- Hard cap: 2–3× your typical monthly spend, plus enough margin that a runaway incident would be costly but not catastrophic. If you do not yet know your typical monthly spend, set $50 as the hard cap and adjust after 90 days.
Verify
After setting the scope and cap, verify with one call. On the Claude Code CLI or in the Cowork tab, make a normal request that uses the cloud provider (a small summarization is enough). Confirm it works. Then open the provider’s usage page and confirm the request was attributed to the new, scoped key — not an old one. If you see usage still attributed to the old key, something is still reading it; go find that consumer and update it.
Canonical recipe entry
The Recipe Book entry /recipe-book/setting-a-hard-cap-on-cloud-spend/ carries the current console paths for Anthropic, OpenAI, and Google. Those entries are dated and versioned. This lesson stops at the conceptual level and the specific numbers above.
The rotation drill RECIPE
| Tools | Anthropic Console (web) · OS secret store (Keychain / Credential Manager / secret-tool / pass) |
| Versions tested | console as of 2026-04-20 · macOS Keychain 15.x · Windows Credential Manager 11 · libsecret current |
| Last verified | 2026-04-20 |
| Next review | 2026-07-20 |
| Supported OSes | macOS, Windows, Linux |
This is the practice-it-once-before-you-need-it block. A rotation you have never done is a rotation you will postpone the first time you need it. Do the drill now.
Pick the key. The right key for the first rotation drill is the cloud-provider key you just scoped and capped above — it has the largest blast radius and is the most likely key to have grey-zone leakage in a Module 1–8 student’s history. If you have already rotated this key recently, pick a different one you depend on.
The five steps
Every rotation has these five steps, in this order.
Step 1 — Generate the replacement in the provider’s console. Give it a name that reflects the rotation date (for example, anthropic-adc-2026-04). Scope it the same way as the current key.
Step 2 — Update the one secret store with the new value. Verify by reading the new value back from the store.
# macOS — update then read back to confirm
$security delete-generic-password -a "$USER" -s ANTHROPIC_API_KEY
$security add-generic-password -a "$USER" -s ANTHROPIC_API_KEY -w
$security find-generic-password -a "$USER" -s ANTHROPIC_API_KEY -w
# Linux (libsecret) — update then read back
$secret-tool clear service anthropic key ANTHROPIC_API_KEY
$secret-tool store --label="Anthropic API key" service anthropic key ANTHROPIC_API_KEY
$secret-tool lookup service anthropic key ANTHROPIC_API_KEY
# Windows PowerShell (Credential Manager, via cmdkey)
>cmdkey /delete:ANTHROPIC_API_KEY
>cmdkey /generic:ANTHROPIC_API_KEY /user:"$env:USERNAME" /passStep 3 — Force every consumer to re-read. On the Claude Code CLI path, close and reopen the session (so it reads the new env var). On the Cowork-tab path, update the key in the tab’s settings pane and save. For any scheduled tasks, run them once manually to confirm they succeed on the new key. The step matters: you cannot assume consumers pick up the new value until you have verified they did.
# Re-export in a fresh shell — the Claude Code CLI inherits the new value on next launch
$export ANTHROPIC_API_KEY="$(security find-generic-password -a "$USER" -s ANTHROPIC_API_KEY -w)"
$echo "${ANTHROPIC_API_KEY:0:8}..." # print only a prefix — never the full valueStep 4 — Confirm the new key is being used. Open the provider’s usage page; make one inference call; see the call attributed to the new key. If it is attributed to the old key, go find the consumer still reading the old value.
Step 5 — Revoke the old key. In the provider’s console, delete or disable the old key. Do not keep it “just in case” — keeping it indefinitely defeats the purpose of the rotation.
Total time
A practiced student does this quickly. A first-time student takes longer, mostly because they discover consumers they did not know were reading the key. Both are fine. The goal of the drill is not speed; it is having done it once so the next time is not the first time.
After-action note
After the drill, write two sentences into /capstone/security-posture.md (in Section 4, which you will finalize in the activity below): “Rotated the Anthropic key on 2026-04-18. Discovered one scheduled task was still reading the old key; fixed.” The note is not for posterity; it is for the 90-day review, where you will re-read your own after-actions and notice patterns (the same kind of consumer always being missed, for example).
Canonical recipe entry
The Recipe Book entry /recipe-book/rotating-an-api-key/ carries the per-provider console paths and per-OS store commands. Those entries are dated and versioned.
Try it — Collapse, scope, cap, rotate RECIPE
four deliverables · printable register: key rotation register → · posture template: security posture template →
Deliverables. One secret store with every secret in it; one cloud-provider key scoped and capped; one full rotation completed and documented; Section 4 — Secrets posture of /capstone/security-posture.md written.
Part 1 — Inventory. Open the security posture template and work through the inventory table. List every secret in your setup and every place it currently exists. This is the hardest step for most students; keep at it until the table is honest. If you finish and feel the table is too short to be true, go back and look for secrets in places you did not initially check (scheduled-task definitions, plugin settings, old scripts, sync services, notes apps).
Part 2 — Collapse to one store. Pick your one secret store from the options above. Move every secret into it. Update every consumer to read from the store. Delete local copies everywhere you can. For grey-zone leaks you cannot delete from (old commits, old chats, old notes), mark them on the inventory table as “assumed leaked — rotation required.”
Part 3 — Scope and cap the cloud-provider key. Create a scoped project in the cloud provider’s console. Generate a new key scoped to that project. Update the one secret store with the new key. Delete the old broader key. Set a monthly cap and an alert threshold.
Part 4 — Rotation drill. Run the five-step rotation against the scoped key you just created. (Yes, you just made it — rotate it anyway. The drill is to practice rotation, and the first one is always the slowest.) Confirm every consumer is reading the rotated key. Revoke the pre-rotation key. Write the after-action note. Log it on the printable key rotation register.
Part 5 — Write Section 4 of the posture document. In /capstone/security-posture.md, fill Section 4 — Secrets posture with the following structure:
## 4. Secrets posture
**My one secret store:** <OS keychain | provider vault | ~/.config/...>
**How consumers read from it:** <one-sentence summary for each of:
shell env vars -> Claude Code; Cowork settings pane; scheduled tasks>
**Secrets currently in the store (names only — no values, ever):**
- ANTHROPIC_API_KEY (scoped to project: ai-architect-academy)
- OPENAI_API_KEY (if used)
- GITHUB_TOKEN (if used)
- <any others>
**Per-key caps and alerts:**
- ANTHROPIC_API_KEY: cap $<N>/month, alert at $<M>
- <others similarly>
**Rotation cadence:** every 90 days, plus immediately on any suspected
leak. *Next rotation:* <date, 90 days out>.
**Grey-zone leaks I am assuming real (and have rotated):**
- <list from the inventory's "assumed leaked" column>
**Plugins and MCPs with their own credentials:**
- <plugin/MCP> — credentials in: <Cowork settings / MCP settings / etc.>
last-reviewed: <date>Part 6 — Save the rotation after-action note as an appendix. Add the two-sentence after-action note from the drill to the bottom of Section 4 under a subheading Rotation log:. Future rotations will append to this list. The log becomes the thing you re-read at every 90-day review.
If this activity feels like overkill
It is not overkill. If you finish this activity and think “that was unnecessary,” your baseline was probably better than most, and the activity refined rather than overhauled — which is fine. If you finish this activity and think “that took way longer than I expected,” your baseline was typical, and the time you spent was the time it would take an incident to force you to do this anyway, paid up front instead. The deal Module 9 is making with you is: spend the time once, get a posture you can lean on for a year.
Done with the hands-on?
When the recipe steps and any activity above are complete, mark this stage to unlock the assessment, reflection, and project checkpoint.
Quick check
- You pasted an API key into a Cowork-tab chat two weeks ago “to debug why this plugin isn’t working,” then deleted the message thirty seconds later. Under Module 9’s definition of “leaked,” is this key leaked or not? What do you do?
- Your cloud-provider key is used by the Claude Code CLI, the Cowork tab, two scheduled tasks, a hobby script on your other laptop, and one published GitHub gist from a year ago. Under the “one secret store” rule, how many copies of the key should exist by the end of Lesson 9.3? What about the gist?
- A student says, “I don’t need a monthly cap because I trust myself not to overspend.” What does the lesson say back?
Answers you can check against yourself: (1) Leaked. The transcript was stored before deletion, and once the message crossed the wire the secret was in a place it should not have been. The correct response is rotation — run the drill against this key. (2) One copy — the one store. Every consumer reads from the store at the time it needs the value. The GitHub gist is worse than leaked; it is public and indexed. Rotate first, then deal with the gist: delete it (gists have edit history, so the old revision with the key is still visible — the delete is mostly symbolic), and assume the key in that gist has been scraped. Your rotation is what actually protects you, not the gist deletion. (3) Something like: “The cap is not a constraint on you; it is a constraint on the scenarios where you are not the one operating the system — a leaked key, a runaway pipeline, a compromised plugin. Trust in yourself does not bound any of those. The cap is the second line of defense after the audience-equals-you rule and is the single highest-impact knob in Module 9.”
Quiz
Four questions. Tap a question to reveal the answer and the reasoning.
Show explanation
Answer: C. The provider’s own console is where the secret was generated — authenticating there is what the secret is for, and no leak occurred. (A), (B), and (D) all count as leaked under the Module 9 rule: the transcript was stored, the screenshot propagates through cloud services, and git history preserves the secret even after removal.
Show explanation
Answer: C. The provider console remains because that is where the key is generated; the one secret store is where every consumer reads from. All four other copies are deleted (including scrubbing the notes-app page). (A) is the pre-lesson baseline. (B) is close but does not name the specific convention. (D) would leave every consumer without a value to read from locally.
Show explanation
Answer: B. This is exactly what the cap is for — a hard stop that converts a potential $400 incident into a $20 one. The student’s next move is to investigate (Lesson 9.5 treats this under the incident loop), fix the loop (Lesson 8.5’s runaway rails are what should have caught this), and decide whether to raise the cap (usually not — the fix is to repair the loop, not to loosen the constraint). (A) is the no-cap baseline. (C) is unusual and not the default behavior for any major AI provider. (D) is wrong; a “hard cap” that is advisory is a soft cap, not a hard one.
Show explanation
Answer: B. This is the lesson’s claim. (A) is an evasion. (C) is not how most providers’ keys work. (D) is out of scope — the course is explicit that regulatory/compliance frameworks are not the target.
Reflection prompt
From five-to-ten copies down to one.
Write a short paragraph (4–6 sentences) in your journal or my-first-loop.md in response to the following: How many copies of your cloud-provider key did you find in your setup at the start of this lesson? How many are there now? Were there any places you did not initially think to look (a sync service, an old script, a notes page, a plugin’s internal settings) that turned up a copy you had forgotten? What does your grey-zone-leak column look like — did you have to rotate for one, for several, or for none? What is the one habit that, going forward, will most reduce the chance that a new grey-zone leak sneaks in?
The purpose is to notice the move from “secrets are something I will deal with if there is a problem” to “secrets live in one place, every consumer reads from that place, and leaks — real or assumed — get rotated immediately.” This is the posture Module 9 is building. You are now operating it.
Project checkpoint
Write Section 4 of the security posture document.
By the end of this lesson, you should have:
- One secret store set up and all secrets collapsed into it (or into the store-equivalents named for the Cowork tab’s own settings pane).
- The cloud-provider key scoped to a named project and capped with a monthly dollar limit and alert threshold.
- One full rotation drill completed, with the after-action note written.
- Section 4 — Secrets posture of /capstone/security-posture.md fully written, including the rotation log at the bottom.
- All grey-zone-leaked secrets rotated.
Section 4 — Secrets posture. My one secret store is: [OS keychain / provider vault / ~/.config/...]. Rotation cadence: every 90 days, plus immediately on any suspected leak. Per-key cap: $[N]/month on the cloud-provider key, alert at $[M]. Plugins / MCPs with their own credentials: [list — each with its store and last-reviewed date]. Rotation log: one line per rotation, dated, with the after-action note.
Do not proceed to Lesson 9.4 until every secret in your setup lives in the one store, the cloud-provider key is scoped and capped, and you have rotated a real key once end-to-end. The posture claim is built out of the practice; the practice is not optional.
Next in Module 9
Lesson 9.4 — Local vs. cloud: routing data with intent.
You will walk every artifact in your capstone folders — /capstone/pipeline-v1/, my-first-loop.md, your posture document itself, Module 5’s inbox/calendar posture, and so on — and label each artifact as public / personal / sensitive. From that classification, you will derive explicit routing rules for which model each data class goes to. Then you will actually re-route one sensitive flow to a local model as a drill, and finish the pipeline-specific portion of Section 3 (trust boundaries) that Lesson 9.2 deferred.