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
For response bodies, headers, health checks, and API calls, replace raw
with
(
). It accepts native curl options and uses Vercel authentication to access protected preview and production deployments.
bash
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:
Inspect
to confirm the linked project and team. Run
only when the directory is not linked or is linked to the wrong project. Run
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:
text
x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>
Use a browser tool that supports origin-scoped request headers. With
, inject development variables without printing or persisting the token:
bash
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
, refresh local development credentials with:
bash
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
.
Use
x-vercel-trusted-oidc-idp-token
for Trusted Sources. Do not substitute
; 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
→
.
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
→
environment pair. A local token has the
environment, so access to protected Production requires
→
.
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
- An application-generated or after Vercel protection is bypassed belongs to the application's own authentication and must be debugged separately.
- A deployment marked 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 repeatedly after receiving the protection page.
- Do not start an interactive SSO browser login when or an origin-scoped OIDC header can authenticate the request.
- Do not expose in logs, screenshots, committed files, or user-facing output.
Related skills
- General Vercel CLI usage:
- End-to-end application verification: