An agent working on production systems needs permission to act. A request like “fix this deployment” doesn’t tell you upfront which actions it will take or what access it will need. Grant agents broad access and a mistake can affect unrelated resources. Ask for approval at every step and the user has to approve individual actions before they know how the agent intends to solve the problem. Repeated prompts can turn that review into a habit of clicking approve.
Vercel Agent starts by investigating the problem, then proposes a plan showing what it would do and what access it would need. Approving that plan grants the additional permissions to carry it out, so the user can review the proposed fix before authorizing any changes.
Copy link to headingThe plan determines the permissions
For a broken production deployment, Vercel Agent might inspect recent deployments and build logs, then compare the failed deployment with the last known-good one. Read-only access lets that investigation run automatically. If it leads to a proposed redeploy, Vercel Agent requests the additional access in a plan the user can review and approve in one decision.
Access is defined by scopes, the named capabilities recognized by the Vercel authorization system. Any plan requesting access beyond the read-only baseline waits for approval as a whole, including any read-only tasks it contains. In this example, the investigation runs under a separate read-only plan before Vercel Agent proposes the redeploy:
Example plans with the work they cover and the scopes they request.
A short read-only lookup can run without a plan. For longer investigations, Vercel Agent creates a read-only plan so the user can follow its tasks and progress while it runs automatically.
The plan connects what the user wants done to what Vercel Agent is allowed to do:
Intent: The outcome the user asks for.
Work: The tasks Vercel Agent proposes to achieve it.
Access: The scopes those tasks require.
Enforcement: The credentials and API checks that enforce access limits.
Each stored plan records its tasks and progress, with requested scopes attached to each task. The task descriptions explain why access is needed, and the scopes are combined across the plan.
The read-only baseline currently includes every registered scope beginning with read:
. Plans need approval when they request access beyond that baseline or include supported external actions, such as opening a GitHub pull request. Read-only operations can still expose sensitive information, so automatic approval does not mean the work is harmless.
Copy link to headingVercel Agent can only use permissions the user already has
Vercel Agent runs as a Vercel App, which the user authorizes to act on their behalf within a team. That authorization is limited by the user’s existing permissions, so approving a plan cannot grant access the user does not have.
The Vercel OAuth service exchanges that authorization for shorter-lived tokens with specific scopes. These scopes define which capabilities the token permits, such as reading deployments or changing project settings. Vercel APIs check the token on each request to enforce those limits.
A user may authorize Vercel Agent for a team with dozens of projects. A redeploy plan requests deployment write access. Editing environment variables, changing domains, and managing team membership each require their own permissions.
Deployment write access is broader than a single redeploy. Naming deployment X in a plan does not, by itself, restrict the token to that deployment. The runtime, the software that coordinates Vercel Agent’s execution, checks that the plan is active before selecting its approved credential. Vercel APIs check each request against that credential’s permissions.
Copy link to headingApproval determines which permissions Vercel Agent can use
When a user approves a plan that needs additional Vercel access, its requested scopes are checked again and a token is prepared containing the read-only baseline plus the approved permissions. The runtime, the software that coordinates Vercel Agent’s execution, checks that the plan is active before selecting its approved credential. That credential remains subject to its scopes, team, the user’s permissions, and expiry.
The credential used depends on the work:
Which credential Vercel Agent uses for each kind of work.
The model’s instructions tell it when to propose a plan and request approval. If it attempts an operation outside the token’s permissions, Vercel APIs reject the request, even if the model considers the action necessary to complete the task.
A single plan can include Vercel changes and a GitHub pull request. The user reviews both in one plan, while each provider uses separate permissions and credentials. GitHub pull-request access is tied to an owner and repository, so approval to open a pull request in acme/storefront
applies to that repository even if the user also has access to acme/payments
. Opening a pull request there requires its own approval.
Copy link to headingPlans and tokens use the same permission definitions
A proposed plan can request a permission that has been renamed or removed. We initially maintained a separate permission list for Vercel Agent, which could fall out of sync with the OAuth service that issues its tokens. We moved to the same scope definitions so those mismatches could be caught during planning.
At session setup, Vercel Agent loads those definitions from the Vercel scope registry into an in-memory catalog. Fetching the registry requires authorization for the team, while the scope definitions themselves are shared across teams. The catalog supplies the definitions used at three stages:
Plan validation: Requested scopes are normalized, and unknown or malformed names are rejected before the plan is stored or presented for approval.
Approval: The requested scopes determine whether the plan fits within the read-only baseline or needs additional access.
Token preparation: Valid scopes define the credentials for approved work.
For example, a task to update firewall rules might request an outdated scope. The system rejects the proposed plan and returns valid scopes so Vercel Agent can correct it before requesting approval. This catches the mismatch during planning and requires an explicit correction instead of a fallback to broader access.
Fetching the registry adds latency and a service dependency, so Vercel Agent caches the catalog and uses that copy to check stored plans when they are loaded. Those checks reflect the cached definitions until the catalog is refreshed with changes from the registry.
Copy link to headingResuming work requires an active, approved plan
Vercel Agent may receive approval after the original chat request has ended, or lose its connection before carrying out an approved redeploy. The stored plan includes its state, who approved it, and when, alongside its tasks and requested permissions. That record connects the proposed work to the access the user authorized and allows the approval to be checked when work resumes.
Before resuming, the runtime reloads the plan and checks that it is active before selecting a credential with its approved permissions. A stopped plan fails that check, even if its token has time remaining before expiry.
If approval and a request to stop arrive together, the plan can move from waiting for approval to active only if the stop has not already changed its status. The runtime then checks again that the plan is active before using the approved credential.
If the investigation reveals that the current plan needs replacing, Vercel Agent can propose another. A replacement requesting elevated access needs its own approval, giving the user a chance to review the revised work and permissions together.
Copy link to headingWhere permissions need more precision
As Vercel Agent reached more of the platform, we had to correct access rules for actions that involve multiple resources or have different consequences. Attaching a domain can require both domain and project permissions, while staging a firewall rule and publishing it need different levels of access. Scopes need to capture these distinctions while keeping each plan’s access request manageable.
Matching those scopes to a proposed fix requires care throughout planning:
Choosing scopes: Vercel Agent chooses scopes with incomplete information, so it can request too little access and leave a task blocked, or too much and grant more authority than the work needs. Task-level guidance helps it choose, while validation catches invalid scope names. Even a valid scope can grant broader access than necessary.
Describing the work: “Redeploy the last successful build” gives the user a concrete action to assess, while scope names alone leave them to work out the consequences. The plan needs to explain the intended change and make clear which limits the token actually enforces.
Understanding denials: A denied operation could indicate a missing scope, an incorrect resource, or an operation that should remain blocked. Vercel Agent needs to distinguish those cases before requesting additional permissions.
Even with the right permissions, a redeploy requires judgment about whether the selected commit is safe to ship. That depends on the application, the failure, and the proposed fix. The user needs enough information to assess the choice, and Vercel Agent still has to execute it correctly.
Read-only investigation also needs controls for the information it retrieves, including sensitive project configuration and operational details. We chose a read-only baseline so Vercel Agent can investigate before asking for approval, and that choice needs continued review as scopes and the information they expose change. Other systems may need a narrower baseline. Separate controls must govern how retrieved information is handled and where it can go.
Vercel Agent can make a wrong decision or encounter malicious instructions in content it reads, such as build logs. Scoped credentials limit which operations it can perform in either case, but permitted operations can still cause harm. Plans therefore work alongside sandbox isolation, network policy, secret handling, rate limits, audit logs, and service authorization. Our work on security boundaries in agentic architectures explains the separation between an agent, its credentials, and the code it executes.
Copy link to headingFrom investigation to approved action
Authority stays attached to the work that required it. The runtime selects the approved credential for an active plan, and its scopes define the operations Vercel Agent can perform. With the investigation already done, the user can assess a proposed fix and its requested access together.
Try Vercel Agent to investigate an issue in your project. Review what it finds and, if it proposes a change, assess the plan and requested access before approving it.