Automated & Agent Access

AI agents, CI/CD pipelines, MCP servers, and end-to-end testing tools can't complete browser-based authentication challenges. If your project has Deployment Protection enabled, these automated systems receive a login page or a 403 response instead of your deployment content.

You have two options for granting programmatic access. Protection Bypass for Automation lets you pass a bypass secret with each request. Deployment Protection Exceptions make specific preview domains publicly accessible without any authentication.

• A Vercel project with Deployment Protection enabled
• The Member role or above on the team, or the Project Administrator role on the project
• Access to your CI/CD, agent, or testing tool's configuration to set headers or environment variables

Deployment Protection methods are designed for browser-based visitors:

• Vercel Authentication: Redirects to a login page that requires an interactive browser session
• Password Protection: Renders an HTML form that expects user input
• Trusted IPs: Only allows requests from specific IP addresses, which doesn't work for agents running on serverless or cloud infrastructure with rotating IPs

Automated systems making HTTP requests (with fetch, curl, or headless browsers) can't complete these interactive flows. Protection Bypass for Automation solves this by letting you attach a secret to requests, skipping the challenge entirely.

Use Protection Bypass for Automation for most automated access scenarios. It authenticates individual requests with a secret token without making any domain publicly accessible.

Deployment Protection Exceptions make an entire preview domain publicly accessible. Use this only when the domain genuinely needs to be public, not as a workaround for automation access.

1. Enable Protection Bypass and create a secret

   1. From your dashboard, select the project
   2. Go to Settings and select Deployment Protection
   3. Under Protection Bypass for Automation, select Create to generate a new secret
   4. Give the secret a descriptive label, such as "CI pipeline" or "Playwright tests"

   You can create multiple secrets per project and revoke them independently. Vercel automatically sets one secret as the VERCEL_AUTOMATION_BYPASS_SECRET system environment variable in your deployments.

2. Pass the secret with each request

   Include the secret as an HTTP header (recommended) or as a query parameter named x-vercel-protection-bypass.

   HTTP header (recommended)

   curl -H "x-vercel-protection-bypass: $VERCEL_AUTOMATION_BYPASS_SECRET" \
     https://your-deployment.vercel.app/api/endpoint

   Query parameter (for tools that can't set headers)

   https://your-deployment.vercel.app/api/webhook?x-vercel-protection-bypass=your_bypass_secret_here

   Use the query parameter approach for services like Slack, Stripe, or GitHub that send webhook requests to your endpoints but don't support custom headers.

   When using the query parameter method, the secret appears in the URL. URLs are often logged by proxies, CDNs, and server access logs. Prefer the header method when your tool supports custom headers.

3. Store the secret securely

   Add the bypass secret as an environment variable or secret in your CI/CD platform, testing runner, or agent configuration. Don't hardcode it in source files or commit it to version control.

   # Example: set as a CI environment variable
   VERCEL_AUTOMATION_BYPASS_SECRET=your_bypass_secret_here

   If the secret is compromised, revoke it in the Deployment Protection settings and create a new one. Revoking a secret invalidates it for all existing deployments. Redeploy your project so deployments receive the updated VERCEL_AUTOMATION_BYPASS_SECRET value.

For full details on how the bypass works, what it skips, and what it can't override, see Protection Bypass for Automation.

If your automated system needs to access a specific preview domain without any authentication, you can add that domain to Deployment Protection Exceptions. The domain becomes publicly accessible, bypassing all Deployment Protection methods.

Deployment Protection Exceptions are available on Enterprise plans, or with the Advanced Deployment Protection add-on for Pro plans.

To add an exception, follow the steps in Deployment Protection Exceptions.

Trusted IPs restricts access to requests from specific IPv4 addresses or CIDR ranges. This works well for teams behind a corporate VPN with stable IP addresses.

However, automated systems running on cloud infrastructure, such as serverless functions, CI runners, or hosted AI agents, typically have rotating or unpredictable IP addresses. Maintaining an IP allowlist for these systems is impractical and error-prone. Use Protection Bypass for Automation instead of (or alongside) Trusted IPs for these scenarios.

Configure Playwright to include the bypass header on every request:

import { defineConfig } from '@playwright/test';
 
if (!process.env.VERCEL_AUTOMATION_BYPASS_SECRET) {
  throw new Error(
    'VERCEL_AUTOMATION_BYPASS_SECRET is required to run tests against protected deployments',
  );
}
 
export default defineConfig({
  use: {
    baseURL: process.env.VERCEL_PREVIEW_URL,
    extraHTTPHeaders: {
      'x-vercel-protection-bypass':
        process.env.VERCEL_AUTOMATION_BYPASS_SECRET,
      'x-vercel-set-bypass-cookie': 'true',
    },
  },
});

The x-vercel-set-bypass-cookie: true header tells Vercel to set a cookie so that subsequent in-browser navigation during tests doesn't trigger additional protection challenges.

import { defineConfig } from 'cypress';
 
if (!process.env.VERCEL_AUTOMATION_BYPASS_SECRET) {
  throw new Error(
    'VERCEL_AUTOMATION_BYPASS_SECRET is required to run tests against protected deployments',
  );
}
 
export default defineConfig({
  e2e: {
    baseUrl: process.env.VERCEL_PREVIEW_URL,
  },
  env: {
    BYPASS_SECRET: process.env.VERCEL_AUTOMATION_BYPASS_SECRET,
  },
});

Then in your test files, include the header on the first request:

describe('Protected deployment', () => {
  it('loads the home page', () => {
    cy.visit('/', {
      headers: {
        'x-vercel-protection-bypass': Cypress.env('BYPASS_SECRET'),
        'x-vercel-set-bypass-cookie': 'true',
      },
    });
    cy.contains('Welcome');
  });
});

When an AI agent needs to call an API route on a protected preview deployment, include the bypass header in the fetch request:

if (!process.env.VERCEL_AUTOMATION_BYPASS_SECRET) {
  throw new Error(
    'VERCEL_AUTOMATION_BYPASS_SECRET is required to access protected deployments',
  );
}
 
const response = await fetch(
  `${process.env.VERCEL_PREVIEW_URL}/api/chat`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-vercel-protection-bypass':
        process.env.VERCEL_AUTOMATION_BYPASS_SECRET,
    },
    body: JSON.stringify({
      prompt: 'Summarize the latest changes',
    }),
  },
);
 
const data = await response.json();

This pattern applies to any programmatic HTTP client, whether it's an AI agent, a background job, or a microservice calling your Vercel deployment.

If you run an MCP (Model Context Protocol) server that fetches data from protected Vercel preview deployments, include the bypass header in outgoing requests. This applies to any MCP tool implementation that reads from or writes to your preview URLs.

if (!process.env.VERCEL_AUTOMATION_BYPASS_SECRET) {
  throw new Error(
    'VERCEL_AUTOMATION_BYPASS_SECRET is required to access protected deployments',
  );
}
 
async function fetchFromPreview(path: string) {
  const baseUrl = process.env.VERCEL_PREVIEW_URL;
  const response = await fetch(`${baseUrl}${path}`, {
    headers: {
      'x-vercel-protection-bypass':
        process.env.VERCEL_AUTOMATION_BYPASS_SECRET,
    },
  });
 
  if (!response.ok) {
    throw new Error(
      `Request failed: ${response.status} ${response.statusText}`,
    );
  }
 
  return response.json();
}

Third-party services like Slack, Stripe, and GitHub send webhook requests to your endpoints but can't set custom HTTP headers. Use the query parameter method to let these requests through:

https://your-app.vercel.app/api/webhooks/stripe?x-vercel-protection-bypass=your_bypass_secret_here

For more webhook examples, see Protection Bypass for Automation.

Pass the bypass secret as a repository secret and use it in your workflow:

name: Preview deployment tests
 
on:
  deployment_status:
 
jobs:
  test:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests against preview
        env:
          VERCEL_AUTOMATION_BYPASS_SECRET: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}
          DEPLOYMENT_URL: ${{ github.event.deployment_status.target_url }}
        run: npx playwright test

The vercel curl command handles bypass tokens automatically, so you can test protected endpoints without manual secret management:

vercel curl /api/hello

• Create one secret per system: Give each CI pipeline, testing suite, and agent its own secret. If one is compromised, revoke it without disrupting the others.
• Never commit secrets to source control: Store them in your CI/CD platform's secret management, your cloud provider's secrets manager, or encrypted environment variables.
• Rotate secrets periodically: Delete the old secret in your project settings and create a new one. Redeploy your project so the VERCEL_AUTOMATION_BYPASS_SECRET environment variable reflects the new value.
• Prefer headers over query parameters: Headers keep the secret out of URL logs, browser history, and referrer headers.
• Scope access narrowly: If only a specific preview domain needs to be accessible, consider Deployment Protection Exceptions for that domain rather than a project-wide bypass secret.

Verify the bypass secret value matches what your project expects. The most common cause is a mismatch between the secret in your CI/CD environment and the one configured in Deployment Protection settings.

Check the following:

1. Confirm the x-vercel-protection-bypass header (or query parameter) is present on the outgoing request
2. Confirm the secret value matches one of the active secrets listed in Settings > Deployment Protection > Protection Bypass for Automation
3. If you recently regenerated the secret, redeploy your project so deployments receive the updated VERCEL_AUTOMATION_BYPASS_SECRET environment variable

When you regenerate a bypass secret in project settings, existing deployments still reference the old value through the VERCEL_AUTOMATION_BYPASS_SECRET environment variable. Redeploy your project after regenerating the secret. Then update the secret value in your CI/CD platform, agent configuration, or testing tool to match the new secret.

Headless browser tools like Playwright and Cypress send the bypass header on the initial page load, but subsequent in-browser navigations (clicking links, form submissions) don't include custom HTTP headers. Include the x-vercel-set-bypass-cookie: true header on the first request to set a cookie that authenticates subsequent browser navigation within the same session.

If the deployment renders inside an iframe, set the value to samesitenone instead of true to ensure the cookie is sent on cross-origin iframe requests.

Automated systems on serverless platforms, cloud infrastructure, or shared CI/CD runners have IP addresses that change between requests. Use Protection Bypass for Automation instead of Trusted IPs for these systems.

Protection Bypass for Automation works for API-level agent access, where the agent makes HTTP requests directly. However, some agents need to interact with protected deployments through a full browser. Visual testing tools, accessibility auditing agents, and web scrapers need to render pages, execute JavaScript, and navigate between routes.

For these browser-based workflows, Vercel's agent-browser can handle authentication flows like Vercel Authentication and Password Protection on behalf of the agent. This lets browser-driven agents access protected deployments without configuring bypass secrets or making domains public.

• Protection Bypass for Automation: Full reference for bypass secrets, including what gets bypassed and what doesn't
• Deployment Protection Exceptions: Make a specific preview domain publicly accessible
• Deployment Protection overview: Configure protection methods and scope
• Trusted IPs: Restrict access by IP address
• Methods to bypass Deployment Protection: All available bypass methods
• vercel curl CLI command: Test protected endpoints from the command line