access-protected-vercel-deployment

When a test site sits behind a company login, scripts and automated browsers reach that login page instead of the site; this gets them through on the Vercel account you already have, rather than taking the lock off.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (6)

Access Protected Vercel Deployments

Use the caller's existing Vercel authentication. Do not disable Deployment Protection or ask for a long-lived bypass secret as the first solution.

Choose the access path

HTTP requests: use `vercel curl`

For response bodies, headers, health checks, and API calls, replace raw curl with vercel curl (vc curl). It accepts native curl options and uses Vercel authentication to access protected preview and production deployments.

vc curl https://my-app.vercel.app/api/health
vc curl https://app.example.com/api/health
vc curl my-app.vercel.app/api/users -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada"}'
vc curl /api/health

The path-only form targets the linked project's production deployment. Pass a full URL when the exact deployment matters.

If authentication fails, check the local identity and project before changing protection settings:

vc whoami

Inspect .vercel/project.json to confirm the linked project and team. Run vc link only when the directory is not linked or is linked to the wrong project. Run vc login only when the CLI reports that no authenticated user is available.

Browser automation: attach the development OIDC token as a header

Browser requests must include the short-lived local token as a request header:

x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>

Use a browser tool that supports origin-scoped request headers. With agent-browser, inject development variables without printing or persisting the token:

vc env run -- sh -c \
  'test -n "$VERCEL_OIDC_TOKEN" && agent-browser open "$1" --headers "{\"x-vercel-trusted-oidc-idp-token\":\"$VERCEL_OIDC_TOKEN\"}"' \
  sh https://my-app.vercel.app

Then continue the normal browser workflow in the same session. For Playwright or another browser driver, set the same header in the browser context's extra HTTP headers before the first navigation.

If the local CLI version does not provide the token through vc env run, refresh local development credentials with:

vc env pull .env.local --yes

Load the file through the project's existing dotenv mechanism. Never print the token, paste its value into source code, or commit .env.local.

Use x-vercel-trusted-oidc-idp-token for Trusted Sources. Do not substitute x-vercel-oidc-token; that header carries an OIDC token into a Vercel Function and serves a different purpose.

Trusted Sources rules

A local development token for a linked Vercel project can access that same project's Preview deployments by default. It does not automatically access protected Production deployments. For protected Production, the project's own Trusted Sources entry must allow development → production.

Do not ask the user to configure Trusted Sources for the normal same-project Preview case.

Configuration is needed when:

the target is a protected Production deployment and the caller uses a local development token;
the caller belongs to another Vercel project or team;
the target project's self-access rules were customized; or
the response is TRUSTED_SOURCES_ENVIRONMENT_MISMATCH.

In the target project, open Settings → Deployment Protection → Trusted Sources. Add or edit the caller and allow the required from → to environment pair. A local token has the development environment, so access to protected Production requires development → production.

Treat this as an access-control change: explain the exact rule required and obtain authorization before changing it. Do not broaden unrelated environment pairs.

Diagnose the response

A Vercel login, SSO, or Deployment Protection page means the request did not use an accepted authentication path.
TRUSTED_SOURCES_ENVIRONMENT_MISMATCH means the token is valid but its caller environment is not allowed to reach the target environment.
An application-generated 401 or 403 after Vercel protection is bypassed belongs to the application's own authentication and must be debugged separately.
A deployment marked "target": "production" can still be protected. Do not assume production is public.

Avoid

Do not disable Deployment Protection to make automation pass.
Do not send raw unauthenticated curl repeatedly after receiving the protection page.
Do not start an interactive SSO browser login when vc curl or an origin-scoped OIDC header can authenticate the request.
Do not expose VERCEL_OIDC_TOKEN in logs, screenshots, committed files, or user-facing output.

Related skills

General Vercel CLI usage: ⤳ skill: vercel-cli
End-to-end application verification: ⤳ skill: verification

This skill ships inside the Vercel Plugin. Listed package contents include 4 slash commands, 3 agents, hooks and an MCP server. Installed components and skill versions may vary by AI tool.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add vercel/vercel-plugin --skill "access-protected-vercel-deployment" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Vercel Plugin package selected for your AI tool.

Run this command in a terminal

npx plugins add vercel/vercel-plugin

Plugins CLI 1.3.4 sends an install report by default, including the source exactly as entered, plugin names, target tools and scope; it does not check whether repositories are public or private. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable this report. For data sent by an installed plugin, check that plugin's documentation.

Open plugin page ↗

What's inside

Files included with this skill.

View on GitHub