Keys, scope, and what to do the day one leaks

An agent's API key is not like a database password, because the blast radius is not data, it is correspondence. Someone holding it can send mail that appears to come from your company, to anyone, and the damage is done the moment it lands rather than when you notice.

29 July 2026 · 5 min read

Scope is the design decision, not the storage#

A key belongs to one agent identity: one handle, one mailbox, one credential. That is what makes everything downstream tractable. The key decides which contacts, notes, and secrets the tools can reach, so an agent cannot read another agent's mail or send from an address it does not own.

Two keys, two agents, two independent revocations. One key shared between five agents means you cannot answer who sent a message and cannot turn one of them off. This is the same argument as agent inbox or shared mailbox, one level down: it applies to keys inside a workspace just as it applies to mailboxes across a company.

The design question per agent: what is the worst message this key could send, using only what it can reach? Then reduce until the answer is acceptable. A scheduling agent needs almost nothing. A support agent rarely needs contact write access.

Where a key should live#

• A secret manager or platform secret, injected as an environment variable. Worker secrets, container secrets, whatever your platform provides.
• Not in code, not in a repository, including private ones, and not in a config file that ends up in an image layer.
• Not in a prompt. This is the agent-specific one. Anything in a system prompt is in your traces, your logs, and your model provider's request history. Give the runtime the key and let it authenticate; the model never needs to see it.
• Not in a message body, and never requested from a human by email. Credentials the agent needs for other services belong in the vault, granted per agent, per contacts, notes, and vault.

Rotation, without pretending it is free#

Rotation is worth doing on a schedule and worth doing properly, which means overlapping rather than swapping. Create the new key, deploy it, confirm the agent is working on it, then revoke the old one. A swap in one step produces a window where the agent is down and mail is not being answered.

A sensible cadence for most teams: rotate every ninety days, immediately on any personnel change for keys a person could have copied, and immediately on suspicion. Rotating more often than you can do calmly is worse than rotating less often and doing it right.

The thing that makes rotation cheap is the thing that makes everything else cheap: one key per agent means one deployment target per rotation, and no coordination across teams.

The hour after a leak#

A key in a public repository, a screenshot, a paste in the wrong channel. The order matters, because the goal is to stop outbound mail before you understand what happened.

1. Revoke the key. Not rotate, revoke. Understanding comes second; a live key is still sending.
2. Read that identity's sent mail for the exposure window. The audit trail records every message against the identity with the key that sent it, which is what makes this a filter rather than an investigation.
3. Check for first sends to new domains. That is the exfiltration shape and the alert you should already have, per what to monitor in production.
4. Check what else that agent could reach: granted secrets, contacts, notes. Anything it could open, treat as opened.
5. Rotate any vault secrets that agent was granted, at the third-party service, not just here.
6. Issue a new key and redeploy the agent.
7. Write down how it leaked and fix that, because the same path will be used again otherwise.

What limits you get for free while you respond#

A leaked key is bad and bounded. Five recipients per message, per-key rate limits, a daily and monthly send allowance, suppression on addresses that already bounced or complained, and duplicate-content and velocity tripwires on cold sends. Someone with your key cannot run a campaign through it, which is the difference between an incident and a catastrophe. The reasoning is in keeping an autonomous agent from becoming a spam problem.

That is a floor, not a plan. It buys you the time to notice.

OAuth, and when it fits better#

Some clients cannot hold a static key, and for those OAuth 2.1 is the right path: dynamic client registration, PKCE required, and the token audienced to the MCP endpoint. The scoping model differs in an important way, though. A key identifies an agent; a token identifies a person. If that person owns several agents, the call must say which one it is acting as with an X-MCPmailer-Agent header, or it is refused as ambiguous rather than guessed at.

Prefer a scoped key for anything you deploy and control. Use OAuth for hosted clients where the credential cannot be stored. Details in OAuth.

A key hygiene checklist#

1. One key per agent identity, never shared.
2. Stored in a secret manager, injected at runtime.
3. Never in a prompt, a repository, an image, or a message.
4. Rotated on a schedule with overlap, and immediately on personnel change.
5. Each agent granted only the secrets, contacts, and notes it needs this week.
6. Alerting on first sends to new domains and on volume changes.
7. A revocation runbook someone has actually read.
8. Vault secrets rotated at the third party when an agent is compromised, not just here.

Questions#

How should AI agent API keys be scoped?

One key per agent identity. The key determines the mailbox it can send from and the contacts, notes, and secrets it can reach, so per-agent scoping makes revocation and attribution independent.

Where should an agent's API key be stored?

In a secret manager or platform secret, injected as an environment variable at runtime. Never in code, a repository, an image layer, a prompt, or a message body.

Why must a key never appear in a prompt?

Because it then exists in every trace, log, and provider request record for runs using that prompt, with retention you do not control. The runtime should authenticate; the model never needs the key.

How often should keys be rotated?

Roughly every ninety days, plus immediately on personnel change or suspicion, using overlapping rotation: deploy the new key, confirm it works, then revoke the old one.

What is the first thing to do if a key leaks?

Revoke it. Investigation comes second, because a live key is still sending. Then read the identity's sent mail for the exposure window and rotate any vault secrets it was granted.

How bad is a leaked agent key?

Bounded rather than catastrophic: five recipients per message, per-key rate limits, daily and monthly allowances, suppression, and tripwires on cold sends mean it cannot become a campaign. That buys time, it does not replace revocation.