> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdecipher.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Host Headers

> Bypass authentication on preview deployments by injecting custom HTTP headers

Custom Host Headers let you inject custom HTTP headers when
Decipher's test runner visits URLs that match a given hostname. This is
useful for bypassing authentication on preview deployments — for example,
Vercel's deployment protection.

## How Hostname Matching Works

Decipher matches hostnames using **subdomain matching**. When you add a
hostname like `vercel.app`, it will match any URL whose host ends with
that value — for example `my-app-git-feat-acme.vercel.app`.

This means you only need one entry per hosting provider, not one per
preview URL.

## Setting Up Custom Host Headers

1. Go to [**Settings > Testing Headers**](https://app.getdecipher.com/settings?section=testing-headers)
2. Under **Custom Host Headers**, click **Add Hostname**
3. Enter the hostname to match (e.g., `vercel.app`)
4. Add one or more HTTP headers as key-value pairs
5. Click **Save**

Any test that navigates to a matching URL will automatically include the
configured headers in its requests.

## Vercel Example

Vercel's [Deployment Protection](https://vercel.com/docs/deployment-protection)
blocks unauthenticated access to preview deployments. You can bypass it
by sending a secret header.

### Step 1 — Get your bypass secret

1. Open your Vercel project's **Settings > Deployment Protection**
2. Under **Protection Bypass for Automation**, copy the secret value

### Step 2 — Add the hostname and header in Decipher

1. In Decipher, go to [**Settings > Testing Headers**](https://app.getdecipher.com/settings?section=testing-headers) and find **Custom Host Headers**
2. Click **Add Hostname** and enter `vercel.app`
3. Add a header:
   * **Key:** `x-vercel-protection-bypass`
   * **Value:** the secret you copied from Vercel
4. Click **Save**

<Tip>
  Decipher's test runner automatically injects the companion header
  `x-vercel-set-bypass-cookie: samesitenone` alongside your bypass header
  so the protection cookie works correctly across navigations.
</Tip>

## Custom Script

Sometimes static HTTP headers aren't enough — for example, when you need
to compute an HMAC signature, attach a rotating token, or dynamically
modify requests at runtime. **Custom Script** lets you write a JavaScript
snippet that runs in the browser before any page scripts on every page
load during a test.

### When It Runs

Whenever a test navigates to a URL whose host matches the configured
hostname, the script is injected and executed **before** the page's own
scripts run. This happens on every navigation (initial load, client-side
route change, or redirect) to the matching host.

### What It Has Access To

The script runs in the page's browser context, so it has access to all
standard browser APIs:

* `window` and `document`
* `fetch` and `XMLHttpRequest`
* `localStorage` and `sessionStorage`
* Cookies via `document.cookie`

### Setting Up a Custom Script

1. Go to [**Settings > Testing Headers**](https://app.getdecipher.com/settings?section=testing-headers)
2. Under **Custom Host Headers**, click **Add Hostname** (or edit an existing one)
3. Write your JavaScript in the **Custom Script** editor
4. Click **Save**

### Example — Injecting a Header into Every Fetch Request

```javascript theme={null}
const originalFetch = window.fetch;
window.fetch = function (...args) {
  let [resource, config] = args;
  config = config || {};
  config.headers = {
    ...config.headers,
    "my-header": "my-value",
  };
  return originalFetch(resource, config);
};
```

<Note>
  Custom Script and HTTP headers can be used together on the same
  hostname. HTTP headers are added to every outgoing request at the network
  level, while the custom script runs in the page's JavaScript context.
</Note>