An agent asked to “fix this deployment” cannot know in advance which operations that request will require. Giving it broad authority risks collateral damage; prompting the user for every action forces approvals before anyone understands the intended solution, and repeated prompts turn review into routine clicking. Vercel Agent resolves this by investigating first and then presenting a plan that states both the proposed work and the access it needs. Approving that plan authorizes the additional permissions required to carry it out.
Plans, scopes, and the read-only baseline
In the broken-deployment case, Vercel Agent inspects recent deployments and build logs, then compares the failed deployment against the last known-good one. That investigation runs automatically under read-only access. If it recommends a redeploy, the agent asks for the extra access in a single plan the user approves in one decision. Short lookups may proceed without a plan, while longer investigations get a read-only plan so users can follow tasks and progress while it runs.
Access is expressed as scopes — the named capabilities recognized by Vercel's authorization system. A plan that asks for anything beyond the read-only baseline waits for approval as a whole, read-only tasks included.
Plan | Work | Requested scope |
|---|---|---|
Investigate the failure | Inspect recent deployments and build logs, then compare the failed deployment with the last successful one |
|
Redeploy the last known-good build | Create a deployment |
|
A stored plan links four things: the intent the user asked for, the work (tasks proposed to achieve it), the access (scopes those tasks require), and enforcement (the credentials and API checks that hold access to its limits). Each task carries its own requested scopes and a description of why they are needed; scopes are combined across the plan.
The read-only baseline currently covers every registered scope beginning with read:. Plans need approval when they exceed that baseline or include supported external actions such as opening a GitHub pull request. Read-only access can still expose sensitive information, so automatic approval is not a safety guarantee.
Authorization can never exceed the user's own permissions
Vercel Agent runs as a Vercel App that a user authorizes to act for them within a team. Because that authorization is bounded by the user's existing permissions, approving a plan cannot hand out access the user lacks. The Vercel OAuth service trades the authorization for shorter-lived, scope-specific tokens — for example, tokens that permit reading deployments or changing project settings — and Vercel APIs validate the token on every request.
A team authorization may span dozens of projects, but a redeploy plan requests deployment write access only; editing environment variables, changing domains, and managing team membership each need their own permissions. Deployment write access is also broader than one redeploy: naming deployment X in a plan does not restrict the token to that deployment. The runtime — the software coordinating Vercel Agent's execution — confirms a plan is active before selecting its approved credential, and the APIs check each request against that credential's permissions.
From approval to credential
When a user approves a plan that needs additional Vercel access, its scopes are re-checked and a token is prepared containing the read-only baseline plus the approved permissions. That credential stays subject to its scopes, its team, the user's permissions, and expiry, and the runtime re-verifies that the plan is active before using it. Which credential applies depends on the kind of work:
Work | Credential |
|---|---|
Read-only investigation | A baseline token with read-only scopes |
Approved Vercel changes | A token with baseline scopes plus the approved additional scopes |
External actions | Credentials and permissions specific to that provider |
Instructions given to the model tell it when to propose a plan and seek approval, but intent is not the enforcement point: an operation outside the token's permissions is rejected by Vercel APIs even when the model considers it necessary.
A plan may combine Vercel changes with a GitHub pull request, reviewed together while each provider keeps separate permissions and credentials. GitHub pull-request access is bound to an owner and repository, so approval to open a PR in acme/storefront does not extend to acme/payments, even if the user can access both — that pull request needs its own approval.
One scope definition, three checkpoints
Plans can name permissions that were renamed or removed. An early design kept a separate permission list for Vercel Agent, which could drift from the OAuth service that issues tokens. Both now draw on the same scope definitions, so mismatches surface at planning time.
At session setup the agent loads these definitions from the Vercel scope registry into an in-memory catalog. Fetching the registry requires team authorization, but the definitions are shared across teams. The catalog is consulted at three stages:
- Plan validation — requested scopes are normalized and unknown or malformed names are rejected before the plan is stored or shown for approval.
- Approval — the requested scopes determine whether the plan stays within the read-only baseline or needs additional access.
- Token preparation — valid scopes define the credentials for approved work.
If a task such as updating firewall rules requests a stale scope, the plan is rejected and the valid scopes are returned so the agent can correct it before asking for approval — an explicit fix, not a fallback to broader access. Because the registry fetch adds latency and a service dependency, the catalog is cached and stored plans are checked against that cached copy, which reflects the cached definitions until the catalog is refreshed.
Resumption depends on a live plan
Approval may arrive after the original chat request has ended, or the agent may lose its connection mid-execution. The stored plan records its state, who approved it and when, along with its tasks and requested permissions, so authorization can be validated when work resumes.
Before resuming, the runtime reloads the plan and confirms it is active before choosing a credential. A stopped plan fails this check even if its token has not expired. When approval and a stop request arrive together, the plan moves from awaiting approval to active only if the stop has not already changed its status — and the runtime checks activity once more before using the credential. If the investigation shows that a new plan is needed, the agent may propose a replacement; a replacement requesting elevated access needs its own approval, so the user reviews the revised work and permissions together.
Open problems in permission precision
As the agent reached more of the platform, some access rules needed correcting for actions that span resources or differ in consequence: attaching a domain can require both domain and project permissions, and staging a firewall rule needs different access from publishing it. Scopes must capture those distinctions while keeping each plan's request manageable.
Several difficulties persist through planning:
- Scope choice — working with incomplete information, the agent can under-request and leave a task blocked or over-request and gain more authority than the work requires. Task-level guidance helps it choose and validation catches invalid names, but even a valid scope can be broader than necessary.
- Describing the work — “Redeploy the last successful build” gives the user something concrete to assess, whereas scope names alone leave them to infer the consequences. A plan should explain the intended change and be explicit about the limits the token actually enforces.
- Reading denials — a denied operation may mean a missing scope, a wrong resource, or an operation that should stay blocked, and the agent must tell these apart before requesting more access.
Correct permissions do not settle the safety of a redeploy; judging whether the chosen commit is safe to ship depends on the application, the failure, and the fix, and the user needs enough information to weigh the choice. Read-only investigation likewise retrieves sensitive project configuration and operational details, so the baseline itself needs continued review as scopes and what they expose evolve — and other systems may need a narrower baseline. Controls over how retrieved information is handled and where it may go are a separate concern.
The agent may also decide wrongly or follow malicious instructions embedded in content it reads, such as build logs. Scoped credentials bound what it can do in either case, but permitted operations can still cause harm. Plans therefore sit alongside sandbox isolation, network policy, secret handling, rate limits, audit logs, and service authorization; our earlier work on security boundaries in agentic architectures covers the separation between an agent, its credentials, and the code it runs.
Authority stays tied to the work that justified it: the runtime selects the approved credential for an active plan, the credential's scopes bound the available operations, and the user sees the proposed fix and its requested access together once the investigation is complete.
