Permissions for AI Agents: The Design Rules
Permissions for AI agents need three things human roles skip: per-project scope, deny-by-default on irreversible actions, and a real read versus change split.
Most teams design an AI agent's permissions by starting from a human role and trimming it, admin minus a few checkboxes, and calling that scoped access. It is not. A person who hits a boundary they were not supposed to cross usually stops and asks. An agent that hits the same boundary, if nothing technical is actually stopping it, keeps going, because attempting a plausible next step and attempting an authorized one look identical from the inside.
The direct answer: permissions for AI agents need three things a human role model does not: access scoped to a specific project rather than the whole org, a deny-by-default posture on anything irreversible, and a hard split between what the agent may read and what it may change, which most tools collapse into a single setting. Skip any of the three and the gap does not show up until an agent takes an action nobody reviewed in advance.
A role copied from a human account and handed to an agent inherits a default that assumes judgment the agent does not have. The fix is three specific changes: scope the credential to one project instead of the org, deny irreversible actions unless each one is individually allowed back in, and grant read access wider than write access on purpose, since useful context and safe action are not the same risk. All three have to be enforced where the agent's credential is checked, not in the instructions it was given.
Why a Human Role Model Fails an Agent
A role-based permission system built for people assumes the person holding a role exercises judgment on top of it: a manager with delete access does not delete things at random, because judgment sits between the grant and the action. An agent has the grant and, absent a technical boundary, will exercise it whenever a request plausibly implies it should, because it has no equivalent hesitation built in. Defining AI agent scope covers the four boundary types that hold for this reason: project, artifact type, reversibility, and blast radius, each enforced at the access-control layer rather than described in a prompt. Permission design is the layer underneath those boundaries, the actual grant a credential carries before any of the four boundaries can be checked against it.
Scope to the Project, Not the Org
The single highest-leverage decision in agent permission design is also the simplest: an agent's credential should reach one project, not the account's full catalog. Onboarding an AI agent treats this as the day-one default rather than a restriction to loosen later, because an agent that can only see one project cannot make an expensive mistake in nine others, no matter how the request is worded. Onplana scopes agent connections at the personal-access-token level: a token minted for one project cannot reach a second one regardless of what an agent asks it to do, which is a property of the credential, not a rule the agent agrees to follow.
Deny Irreversible Actions by Default
Most permission systems default open: grant a role, and everything not explicitly forbidden is available. That default is backwards for an agent, because a person who reaches an unforeseen edge case pauses; an agent that reaches the same edge case attempts it. The safer default is closed: deny anything that deletes, sends externally, or commits a budget or contract figure, and allow specific actions back in individually, each with its own justification for why this particular agent needs it. Who is accountable when an agent is wrong covers what happens when this default runs the other way: the destructive action already happened, and the review starts from "why was this allowed" instead of "why was this denied."
The diagram below shows the two axes a permission grant needs, scope on one and the read-versus-change split on the other, with the deny-by-default zone marked where they overlap on anything irreversible.
Split Read From Change, on Purpose
An agent that can only read what it is allowed to change is usually not useful, because good decisions need context beyond the one field a task asks it to touch: a status draft is better when the agent can see the whole schedule, not just the task it is summarizing. The mistake most tools make is granting that same wide reach to the change side of the permission, so an agent that can read the whole project can also write to any of it. Read and change need separate settings. Grant read wide enough for real context; grant change to the narrow list of specific actions this agent has been trusted with, reviewed on its own, not inherited from the read grant next to it.
| Setting | Typical default | Better default for an agent |
|---|---|---|
| Project scope | Org-wide, matching the connecting user | Single project, set at the credential |
| Read access | Same as write access | Wide, for context |
| Write access | Same as read access | Narrow, allow-listed action by action |
| Irreversible actions | Allowed unless denied | Denied unless individually allowed |
| Revocation | Delayed token expiry | Immediate, single action |
Permissions for AI Agents Are Not a One-Time Setting
A grant that was correct on day one drifts, usually because someone widened access to unblock a task and never narrowed it back. Security review questions for AI agent access covers Onplana's own model for this: connections gated behind an admin-controlled permission key, concurrent connections capped by plan, and write actions metered separately from read access so the two settings this post argues for are not just a recommendation but the actual enforcement layer. Review the grant on a schedule, the same way audit trail requirements for agent work argues the action log has to be read on a schedule rather than only when something looks wrong, because a permission that quietly widened three months ago will not announce itself.
The principle underneath all three rules here is not new. NIST's definition of least privilege states it for any system: restrict access to the minimum necessary to accomplish the assigned task. What changes for an agent is not the principle, it is how much smaller "necessary" needs to be, because there is no judgment on the other end of the grant to catch what the permission model misses. The rest of the Onplana blog covers the practices this permission model assumes are already in place: onboarding an agent narrow and widening it deliberately, and reviewing what it actually did against the boundary that was supposed to hold.
Frequently asked questions
What does designing permissions for an AI agent actually involve?
Three things a human role model does not need: scoping access to one project instead of the whole org, denying anything irreversible by default rather than trusting the agent's judgment, and separating what the agent may read from what it may change, since most tools grant both together as one setting.
Can an agent do something irreversible if I never explicitly restricted it?
Yes, and that is the design mistake this post argues against. A permission model built for people assumes a sensible default; an agent has no instinct that stops it at a boundary nobody drew, so anything not explicitly denied is implicitly available. Deny irreversible actions by default and allow specific ones back in, rather than the reverse.
Who is accountable if an agent's permissions were set too wide?
Whoever granted the scope, the same as an over-privileged new hire's access is a gap in onboarding rather than the hire's fault. A wide grant that was never reviewed is a standing decision someone made, even if nobody remembers making it.
Can a comment on a task talk an agent into acting outside its permissions?
Only if the boundary lives in the agent's instructions rather than in what its credentials can technically reach. A persuasive comment and a legitimate request read identically to a model, which is why the permission check has to happen in the system the agent calls, not in the prompt it was given.
Should an agent's read access be as wide as its write access?
No, and collapsing the two into one setting is the most common permission-design mistake. An agent usually needs broad read access to do useful work, cross-referencing a schedule against a resource pool, for instance, but the actions it can commit without review should be a much narrower list than the data it can see.
What happens to an agent's access once it is disconnected?
It should end in the same action that removes it, immediately, the way pulling a human teammate's access does. A permission model that leaves cached tokens or delayed revocation live after disconnect has not actually revoked anything, just delayed the exposure.
Ready to make the switch?
Start your free Onplana account and import your existing projects in minutes.