API keys and permissions for an agent

A key the agent holds is a key an attacker can reach. That is the whole reason this page exists, and it makes best practice simpler rather than fussier: if a key can only read one folder, the worst outcome is that one folder gets read.

OWASP's guidance for prompt injection says the same thing in a different register: give the application its own token, minimise what it can reach, and never hand the model a credential that does more than the job needs (LLM01:2025).

Almost everyone starts with a model provider key, because nothing runs without one. Get it, put a spend limit on it, and treat it as the first of several rather than the only one.

GitHub is a good example to learn on, because it shows both designs side by side. A classic personal token reaches every repository you can reach. A fine-grained token is limited to one owner, can be limited to named repositories, and carries named permissions (GitHub docs).

Google's API scopes work the same way: there is normally a read-only scope and a read-and-write scope for each service, and an agent that only reports needs the first (OAuth scopes).

• In an environment file the program reads at start, with permissions set so only your account can read it.
• In your password manager, as the copy you can still find when the file is gone.
• In the provider's dashboard, as the record of what exists and when it was last used.

Not in a prompt, not in a screenshot, not in a chat message, and never in the repository. A committed key is a published key, and it stays in the history after you delete the line.

The tooling that catches this exists and is worth turning on. GitHub's secret scanning reads the full history and alerts on a leaked token, and push protection blocks a commit before a detected secret lands (secret scanning).

Keys are what the world allows. Permissions are what your harness allows, and they are usually a shorter list than people expect: which folders the agent may write to, which commands it may run, and what it must ask about.

Most harnesses express this as a mode plus rules. Claude Code's modes run from read-only planning to accepting edits, with allow, ask and deny lists evaluated most-severe-first (permissions). Codex separates the sandbox from the approval policy, so you can let it write inside a folder while still asking about the network (approvals and security).

What to let your agent touch is the practical half of that: the boundary, the approval queue, and the way to stop it.

Write down every key you have given an agent: what it is, what it can reach, and when you made it. It takes ten minutes and saves the worst hour of the year.

• Set an expiry where the provider allows one, and expect to renew it.
• Check the provider's usage page occasionally. It says whether a key was used, and when.
• When something looks wrong, revoke first and investigate second. Revoking is one action and works on a machine you cannot reach.