# How to set Permissions-Policy on Caddy

> Set Permissions-Policy on Caddy with the header directive, quote origins with backticks, enable a feature on one path and stop a proxied app's policy winning. Tested.

Author: Joshua Martinelle, Security engineer at Tenable (https://www.websec0.com/guides/authors/joshua-martinelle/)
Canonical: https://www.websec0.com/guides/permissions-policy/caddy/
Updated: 2026-10-24
Tested on: Caddy 2.9, 2.10 and 2.11

## In short

- Add `header Permissions-Policy "camera=(), microphone=(), geolocation=(), …"` to the site block, listing every feature your site does not use. Caddy sends it on its own 404 pages and redirects.
- When the policy contains origins, wrap the value in backticks so the origins keep their double quotes. Unescaped double quotes make `caddy validate` fail with a regexp error.
- Behind `reverse_proxy`, the application's policy comes after Caddy's, and for a feature defined in both the last one wins. Add `header_down -Permissions-Policy` inside the proxy block.
- To enable the camera on one path, put that path's `header` line in a `route` block. Outside `route`, the site-wide line runs last and overwrites it.

## The short answer

Add the header to the site block in your Caddyfile, listing the features you
do not use:

```caddyfile
example.com {
	header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()"
	root * /var/www/example
	file_server
}
```

```sh
caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy
```

Every snippet below was run on Caddy 2.9, 2.10 and 2.11 and checked with
`curl`, on a page, a 404, a redirect, a proxied application and an
application that was down.

Remove from the list any feature your site uses. The
[Permissions-Policy overview](/guides/permissions-policy/) explains each
feature, the syntax and why only Chromium browsers apply the header.

## Before you start

Find every site block, `header` directive and proxy in your Caddyfile:

```sh
grep -nE "^[^ \t#].*\{|header|Permissions-Policy|Feature-Policy|reverse_proxy|php_fastcgi|import|route" /etc/caddy/Caddyfile
```

You are looking for:

- **Features your pages use,** such as a video call page that needs the
  camera, or a checkout that uses the Payment Request API (step 4).
- **Every site that serves pages.** Caddy adds no Permissions-Policy on its
  own.
- **Proxied applications** that may send a Permissions-Policy or an old
  Feature-Policy. Two headers cause trouble (step 3).

## Step 1: write a valid value

Caddy does not check the value. Chrome does, and ignores the whole header on
a syntax error:

- Lower-case feature names, no spaces around `=`, commas between features, no
  trailing comma.
- `()` to disable, `(self)` for your origin, `*` for any origin.
- Origins in double quotes: `(self "https://video.example")`.

When the value contains origins, wrap it in backticks, which Caddy reads as
quotes that keep double quotes inside. Escaping the inner quotes with a
backslash works too:

```caddyfile
header Permissions-Policy `camera=(), fullscreen=(self "https://video.example")`
header Permissions-Policy "camera=(), fullscreen=(self \"https://video.example\")"
```

Both lines returned the same header in our test:

```http
HTTP/2 200
permissions-policy: camera=(), fullscreen=(self "https://video.example")
```

Plain double quotes inside a double-quoted value do not work. Caddy ends the
value at the second quote and reads the rest of the line as a find-and-replace
with a regular expression. With a Permissions-Policy, the parentheses make
that expression invalid: `caddy validate` failed on every version with
`error parsing regexp: missing closing )`, and Caddy refused to start with
that configuration.

## Step 2: which responses get the header

A plain `header` line acts on every response of the site. In our test:

| Response | Permissions-Policy |
| --- | --- |
| A page from `file_server` | Present |
| A 404 from `file_server` | Present |
| A `301` from a `redir` in the site | Present |
| A file under `/assets/` with its own `header /assets/* Cache-Control …` line | Present |
| A 502 when the proxied application was down | Present |
| Caddy's automatic HTTP to HTTPS redirect | Absent |

Unlike Nginx and Apache, there is no `always` flag to remember. The automatic
redirect has no page to protect. To send the same headers from several sites,
put them in a snippet that each site imports; the
[security headers hub for Caddy](/guides/security-headers/caddy/) shows one
snippet with all six security headers.

## Step 3: one header behind reverse_proxy

A `header` line runs before the proxy, and Caddy keeps the application's
headers after its own. Our test, with an application sending an old,
permissive policy:

```http
HTTP/2 200
permissions-policy: camera=(), microphone=(), geolocation=()
permissions-policy: geolocation=(self), camera=*, interest-cohort=()
feature-policy: camera *
```

Browsers read the two headers as one policy, and when a feature is defined
twice, the last definition wins. Here the application's `camera=*` comes last:
any site that frames your pages may use the camera. WebSec0 reads the
combined policy the same way and grades it as a warning.

Drop the application's headers as the response comes back from the proxy:

```caddyfile
example.com {
	header Permissions-Policy "camera=(), microphone=(), geolocation=()"
	reverse_proxy 127.0.0.1:8080 {
		header_down -Permissions-Policy
		header_down -Feature-Policy
	}
}
```

Our test then returned a single Permissions-Policy, Caddy's, and no
Feature-Policy, on the application's pages and 404s, and on Caddy's 502 when
the application was down. Do not use the `>` prefix instead: it replaces the
application's value, but Caddy's own error pages then go without the header,
as the [security headers hub for Caddy](/guides/security-headers/caddy/)
shows.

## Step 4: enable a feature on one path

A video call page under `/meet/` needs the camera and the microphone. A
`header /meet/* …` line next to the site-wide one does not work. Caddy sorts
`header` directives by path matcher, the most specific first and the one
without a matcher last, so the site-wide line runs after the per-path one and
overwrites it. In our test, `/meet/` got `camera=()`.

Put the per-path line in a `route` block. Inside `route`, directives run in
the order written, and the block as a whole runs after the site-wide
`header`:

```caddyfile
example.com {
	header Permissions-Policy "camera=(), microphone=(), geolocation=()"
	route {
		header /meet/* Permissions-Policy "camera=(self), microphone=(self), geolocation=()"
	}
	root * /var/www/example
	file_server
}
```

What our test returned:

| URL | Permissions-Policy |
| --- | --- |
| `/` | `camera=(), microphone=(), geolocation=()` |
| `/meet/` | `camera=(self), microphone=(self), geolocation=()` |
| `/meet/does-not-exist` (404) | `camera=(self), microphone=(self), geolocation=()` |

Keep the site-wide line outside `route`: `route` runs after `redir` in
Caddy's directive order, so a redirect would go without the header.

## Verify it

Check a page, an error page and a path with its own policy. Use your own host
name:

```sh
curl -sI https://example.com/ | grep -i "^permissions-policy"
curl -sI https://example.com/does-not-exist | grep -i "^permissions-policy"
curl -sI https://example.com/meet/ | grep -i "^permissions-policy"
```

Each should print the policy you chose for that path. Count the headers to
catch duplicates. The result should be `1`:

```sh
curl -sI https://example.com/ | grep -ci '^permissions-policy:'
```

Then open the page in Chrome with the developer console open: a syntax error
shows up as "Parse of permissions policy failed". Finally, scan the site with
WebSec0. The headers report shows the value it received and whether it
passes.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `error parsing regexp: missing closing )` | Unescaped double quotes around an origin | Wrap the value in backticks. |
| No Permissions-Policy at all | Caddy adds none by default | Add the `header` line to every site, or import a snippet. |
| Two `Permissions-Policy` headers, the application's last | The proxied application sends one too | Add `header_down -Permissions-Policy` inside `reverse_proxy`. |
| `Feature-Policy` still sent | The application sends it | Add `header_down -Feature-Policy`. |
| A feature stays disabled on its path | The per-path line is outside `route`, so the site-wide line overwrites it | Put it in a `route` block. |
| Header missing on 502 pages | `>` in front of the field | Drop the `>` and use `header_down`. |
| Chrome ignores the header | A syntax error, such as an upper-case feature name | Check the console, and fix the value as in step 1. |
| WebSec0 shows a warning | No sensitive feature disabled, or one opened with `*` | Disable the features you do not use with `()`, and remove `*`. |

## Frequently asked questions

### What is the Caddyfile line for Permissions-Policy?

`header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=()"` in the site block. Add the other features your site does not use, then run `caddy validate` and reload.

### How do I put an origin in Permissions-Policy on Caddy?

Origins must be in double quotes in the header. Wrap the whole Caddyfile value in backticks instead of double quotes, so the inner double quotes are kept. Escaping them with backslashes in a double-quoted value also works.

### Why does caddy validate fail with "error parsing regexp: missing closing )"?

A double quote inside a double-quoted value ends the value early. Caddy then reads the line as a find-and-replace with a regular expression, and the parentheses of the policy make that expression invalid. Wrap the value in backticks.

### My response has two Permissions-Policy headers behind reverse_proxy. What happens?

Browsers read them as one policy, and for a feature defined in both, the last definition wins. In our test the application's header came last, so its `camera=*` applied. Add `header_down -Permissions-Policy` inside `reverse_proxy`.

### How do I allow the camera on one URL only on Caddy?

Put `header /meet/* Permissions-Policy "camera=(self), microphone=(self), geolocation=()"` in a `route` block after the site-wide line. Inside `route`, directives run in the order written.

## Sources

- [Caddyfile directive: header](https://caddyserver.com/docs/caddyfile/directives/header), Caddy
- [Caddyfile concepts: tokens and quotes](https://caddyserver.com/docs/caddyfile/concepts#tokens-and-quotes), Caddy
- [Caddyfile directive: reverse_proxy (header_down)](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#headers), Caddy
- [Caddyfile directive: route](https://caddyserver.com/docs/caddyfile/directives/route), Caddy
- [Permissions Policy](https://w3c.github.io/webappsec-permissions-policy/), W3C
- [Permissions-Policy header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy), MDN Web Docs
