Scoped API Credentials for AI Agents: A Checklist

An agent chooses its own next call. That is the point of it, and it is also the problem. If the key in its config can drop a database, then the safety of your database rests on the agent never deciding to, or never being talked into it by text it reads along the way.

OWASP names this class of failure in its 2025 list of risks for LLM applications. Excessive agency, as it calls it, has three roots: too much functionality, too many permissions, and too much autonomy. Its prevention advice is blunt about where the check belongs, which is in the backend system rather than in the model's judgement.

Scoped api credentials are least privilege made practical, and NIST's glossary carries the same idea across several of its publications. An agent is a user in this sense. Treat it like a contractor on their first day, not like you.

1. 11. Make a key per agent, never share yoursOne key, one job, one name. When something odd shows up in the logs, the name tells you which agent did it. A personal key pasted into a tool gives you neither a name nor a way to cut it off without cutting yourself off.
2. 22. Grant the narrowest scopes that workStart from read-only and add write scopes one at a time. Keep read and write separate, so that read access cannot become the power to spend money or delete data.
3. 33. Confine the key to one projectIf the agent is fixing one app, it has no business seeing the others. A key limited to a single project should not be able to choose a different one at call time.
4. 44. Put a spend cap on itAny key that can create billable things needs a hard monthly ceiling. Ask what the worst month looks like if the agent loops, and set the cap to that number, not to your budget.
5. 55. Give it a short lifeHours or days, not forever. A key that expires on its own turns a leak from an incident into a nuisance. Re-minting is cheap.
6. 66. Know how to revoke it, and test itFind the revoke call before you need it. Confirm it stops in-flight requests as well as new ones.
7. 77. Keep secret values out of reachThe agent should be able to use a secret without ever reading it back. If an endpoint can return a value, a leaked read key can take it.

OWASP's secrets management cheat sheet supports several of these directly: rotate secrets regularly so stolen credentials only work for a short time, apply least privilege with fine-grained access controls, revoke securely when a secret is compromised, and treat auditing as essential.

Not all scopes carry the same weight. This table uses Helm7's scope names because they are published in the REST API reference, but the ranking logic transfers to any platform. The risk column is our own assessment, not a standard.

Helm7 was built for agents to use, so its scoped api credentials follow the shape above. This is one example of the pattern, not the only way to do it. The agents page shows it end to end.

• A key resolves to a member and can never exceed what that member can do. The scopes you ask for are intersected with the ones you hold, so asking for too much narrows the key rather than failing.
• A key can carry a hard monthly budget. Calls that cost money are priced first, and one that would go past the cap is refused with the code budget_exceeded.
• A key can carry an expiry in hours. The catalogue's own advice is to prefer a short life and re-mint.
• A key can be confined to one Product. It cannot choose another at call time.
• Capabilities are separate from scopes: may_deploy, may_administer and may_manage_billing. A key with may_administer cannot mint another key with it, which is what makes revoking one mean something.
• The secret is shown once. No endpoint returns a secret value, only names and fingerprints.
• Revoking a key is a destructive operation, so it needs confirm set to true. Once applied, the key stops working immediately, including for requests already in flight.

Tools a key cannot use are left out of the tool list an agent sees. Agents spend fewer turns arguing with permission errors, and the prompt is shorter. The first call an agent should make is whoami, which returns the key's scopes, capabilities, budget and expiry.

For agents that arrive with nothing, cloud_init creates a temporary workspace and a scoped key with no email or card. It expires after 72 hours on the Trial plan and is meant for experiments, not for anything real. On paid plans, the pricing page lists scoped agent credentials with spend caps from the Pro plan, and organisation-wide agent policy on Scale. See pricing for current terms.

Say a two-person team wants an agent to ship the marketing site. Here is how the seven checks turn into one call for scoped api credentials. The id and name are illustrative.

agent_key_create
{
  "name": "release-bot",
  "scopes": ["product:read", "deployment:read", "deployment:write"],
  "product_id": "prd_7k2m9x4qw1nv",
  "budget_usd": 20,
  "expires_in_hours": 8,
  "capabilities": ["may_deploy"]
}

Nothing here can touch a database, change a domain or read a secret. If the key leaks at lunchtime, it is useless by evening and could not have spent more than $20 in the meantime. The cap and expiry are numbers you chose, so the worst case is one you can state in advance.

1. 1Revoke itDo this first and think afterwards. Revoking is quick and re-minting is cheaper than an investigation.
2. 2Read the activity log for that key's nameThis is why every key has its own name. Look for anything that created or changed resources.
3. 3Check spendLook at the usage figure against the cap. If a cap was set, the ceiling on the damage is already known.
4. 4Rotate anything it could reachIf the key had secret write access, treat the variables it could set as suspect.
5. 5Re-mint narrowerAsk what the key never used, and drop it.

A dry run helps here too. If you are unsure what a revoke or a restore will do, the plan shows you first. We cover that habit in why a deploy should show a plan.

Scoped api credentials limit the damage. They do not stop an agent doing something foolish with the permissions it has. A release bot with deploy rights can still ship a broken build. The answer to that is a human checking the plan for the risky steps, which OWASP also recommends for high-impact actions.

It is also worth checking what the tool you connect exposes. MCP servers, the protocol agents use to call tools, are only as safe as the key behind them. Our MCP server guide explains why the credential, not the protocol, decides what a tool can reach.