# How to set Permissions-Policy on Nginx

> Set Permissions-Policy on Nginx with add_header and always, quote origins correctly, keep it on every location and enable a feature on one path only. Tested configs.

Author: Joshua Martinelle, Security engineer at Tenable (https://www.websec0.com/guides/authors/joshua-martinelle/)
Canonical: https://www.websec0.com/guides/permissions-policy/nginx/
Updated: 2026-10-16
Tested on: nginx 1.28, 1.30 and 1.31

## In short

- Add `add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), …" always;` to the `server` block, listing every feature your site does not use.
- When the policy contains origins, wrap the Nginx value in single quotes so the origins keep their double quotes: `'fullscreen=(self "https://video.example")'`.
- Without `always`, 404 and 500 pages are sent without the header. A `location` with its own `add_header` drops it too: use an `include` file or `add_header_inherit merge;` (nginx 1.29.3+).
- To enable the camera on one path, give that `location` its own header. Under `add_header_inherit merge;`, add `add_header_inherit off;` there, or the server's `camera=()` comes last and wins.
- Check the browser console after deploying: Chrome ignores the whole header on a syntax error.

## The short answer

Add the header to the `server` block of your site, listing the features you
do not use:

```nginx
server {
    listen 443 ssl;
    http2 on;
    server_name example.com;
    ssl_certificate     /etc/ssl/example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/example.com/privkey.pem;

    add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()" always;
}
```

```sh
sudo nginx -t && sudo systemctl reload nginx
```

`always` keeps the header on error pages. Every snippet below was run on
nginx 1.28, 1.30 and 1.31 and checked with `curl`, on a page, a 404 and a
nested `location`. We also loaded the policy above in Chrome 152 and checked
that all 14 features were disabled.

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

List every `add_header`, every `include` and every proxied application in the
merged configuration:

```sh
sudo nginx -T | grep -niE "server_name|add_header|include|proxy_pass|fastcgi_pass|permissions-policy|feature-policy"
```

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 5).
- **Locations with their own `add_header`.** They drop the server-level header
  (step 3).
- **An existing Permissions-Policy or Feature-Policy** in Nginx or in the
  application. Two headers cause trouble (step 4), and `Feature-Policy` can be
  removed.

## Step 1: write a valid value

Nginx 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 single quotes in Nginx so the
double quotes reach the browser:

```nginx
add_header Permissions-Policy 'camera=(), microphone=(), geolocation=(), fullscreen=(self "https://video.example")' always;
```

Our test returned the value unchanged:

```http
HTTP/1.1 200 OK
Permissions-Policy: camera=(), microphone=(), geolocation=(), fullscreen=(self "https://video.example")
```

Keep the policy on one line, even if it is long. Nginx accepts a quoted value
that spans several lines, but in our test it sent the line break inside the
header value, which makes the header invalid.

## Step 2: keep it on error pages

Without `always`, Nginx only adds headers to 200, 201, 204, 206, 301, 302, 303,
304, 307 and 308 responses. Our test with
`add_header Permissions-Policy "camera=(), microphone=(), geolocation=()";`:

```http
HTTP/1.1 200 OK
Permissions-Policy: camera=(), microphone=(), geolocation=()

HTTP/1.1 404 Not Found
(no Permissions-Policy header)
```

An error page that loads analytics or a chat widget then runs with every
feature at its default. Keep `always` on the line.

## Step 3: keep it on every location

`add_header` directives are inherited from the parent block **only if the
current block has none**. Here, files under `/assets/` are served without
Permissions-Policy:

```nginx
server {
    listen 443 ssl;
    server_name example.com;
    # ssl_certificate lines...

    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

    location /assets/ {
        # This one line removes the server-level Permissions-Policy for /assets/.
        add_header Cache-Control "public, max-age=31536000, immutable" always;
    }
}
```

The fix that works on every version is a snippet you include wherever a block
sets its own headers:

```nginx
# /etc/nginx/snippets/security-headers.conf
add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), serial=(), hid=(), bluetooth=(), midi=(), display-capture=(), accelerometer=(), gyroscope=(), magnetometer=(), browsing-topics=()" always;
```

```nginx
server {
    listen 443 ssl;
    server_name example.com;
    # ssl_certificate lines...

    include /etc/nginx/snippets/security-headers.conf;

    location /assets/ {
        add_header Cache-Control "public, max-age=31536000, immutable" always;
        include /etc/nginx/snippets/security-headers.conf;
    }
}
```

On **nginx 1.29.3 or later**, which includes the 1.30 stable branch,
`add_header_inherit merge;` makes nested blocks add their headers to the
parent's instead of replacing them:

```nginx
server {
    listen 443 ssl;
    server_name example.com;
    # ssl_certificate lines...

    add_header_inherit merge;
    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

    location /assets/ {
        # Sent together with the server-level Permissions-Policy.
        add_header Cache-Control "public, max-age=31536000, immutable" always;
    }
}
```

nginx 1.28 rejects it with `unknown directive "add_header_inherit"`. The
[Referrer-Policy guide for Nginx](/guides/referrer-policy/nginx/) and the
[X-Frame-Options guide for Nginx](/guides/x-frame-options/nginx/) use the same
snippet for their headers.

## Step 4: one header behind a reverse proxy

When Nginx proxies an application that sends its own Permissions-Policy and
adds its own line, the response carries both, the upstream's first. Our test,
with an application sending an old policy:

```http
HTTP/1.1 200 OK
Permissions-Policy: geolocation=(self), interest-cohort=()
Permissions-Policy: camera=(), microphone=(), geolocation=()
```

Browsers merge the two, and when a feature appears in both, the last
definition wins. In Chrome 152, geolocation ended up disabled by Nginx's
header, and the upstream's obsolete `interest-cohort` stayed in the policy.
When the two headers disagree, the result depends on their order, which is
easy to get wrong.

Pick one owner. If it is Nginx, hide the upstream's header:

```nginx
location / {
    proxy_pass http://app;
    proxy_hide_header Permissions-Policy;
    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
}
```

Use `fastcgi_hide_header` for PHP-FPM and `uwsgi_hide_header` for uWSGI. Hide
`Feature-Policy` the same way if the application still sends it.

## Step 5: enable a feature on one path

A video call page under `/meet/` needs the camera and the microphone. Give
that location its own header and keep everything else disabled:

```nginx
server {
    listen 443 ssl;
    server_name example.com;
    # ssl_certificate lines...

    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

    location /meet/ {
        add_header Permissions-Policy "camera=(self), microphone=(self), geolocation=()" always;
        # Repeat your other security headers here.
    }
}
```

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=()` |

Because the location sets its own `add_header`, it inherits nothing from the
`server` block, so repeat your other security headers in it.

With `add_header_inherit merge;` at server level, Nginx sends the location's
header first and the server's after it:

```http
HTTP/1.1 200 OK
Permissions-Policy: camera=(self), microphone=(self), geolocation=()
Permissions-Policy: camera=(), microphone=(), geolocation=()
```

The server's `camera=()` comes last and wins: in Chrome 152, the camera and
microphone stayed disabled on `/meet/`. Add `add_header_inherit off;` as the
first line of that location:

```nginx
location /meet/ {
    add_header_inherit off;
    add_header Permissions-Policy "camera=(self), microphone=(self), geolocation=()" always;
}
```

Our test then returned only the location's header.

## Verify it

Check a page, an error page and one URL in every `location` that sets its own
headers. 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/assets/app.css | grep -i "^permissions-policy"
```

Each should print your policy. Count the headers to catch duplicates. The
result should be `1`:

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

`curl` cannot tell whether the browser accepts the value. Open the page in
Chrome, open the developer tools console and look for "Error with
Permissions-Policy header". Then scan the site with WebSec0: it parses the
header like Chrome and fails it on a syntax error.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Header missing on 404 or 500 pages | `add_header` without `always` | Add `always` to the line. |
| Header missing on some URLs | That `location` has its own `add_header` | Include the snippet there, or use `add_header_inherit merge;` (1.29.3+). |
| Console: "Parse of permissions policy failed", WebSec0 fails the header | Syntax error in the value | Lower-case names, no spaces around `=`, no trailing comma, origins in double quotes. |
| WebSec0 shows a warning | No sensitive feature set to `()`, or one set to `*` | Disable the features you do not use, such as `camera=()`, and remove `*`. |
| Console: "Invalid allowlist item" | An origin without double quotes, or `none` | Quote origins; use `()` to disable. |
| `nginx -t` fails with `unexpected "h"` | Unescaped double quotes inside a double-quoted value | Wrap the value in single quotes. |
| Header value contains a line break | The value spans several lines in the configuration | Put the whole value on one line. |
| Two `Permissions-Policy` headers | The upstream application sends one too | `proxy_hide_header Permissions-Policy;` or remove the Nginx line. |
| A feature stays disabled on one path | `add_header_inherit merge;` puts the server's header last | Add `add_header_inherit off;` in that location. |
| `unknown directive "add_header_inherit"` | nginx older than 1.29.3 | Upgrade, or use the `include` approach. |

## Frequently asked questions

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

`add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=()" always;` in the `server` block. Add the other features your site does not use, then run `nginx -t` and reload.

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

Origins must be in double quotes in the header, so wrap the whole Nginx value in single quotes: `add_header Permissions-Policy 'camera=(self "https://meet.example")' always;`. Escaping the inner quotes with backslashes in a double-quoted string also works.

### Why is Permissions-Policy missing on my 404 pages?

Without the `always` parameter, Nginx only adds headers to 200, 201, 204, 206, 301, 302, 303, 304, 307 and 308 responses. Add `always` at the end of the `add_header` line.

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

Browsers combine them, and when a feature is defined in both, the last definition wins. Behind a proxy, Nginx's header comes after the application's. Keep one with `proxy_hide_header Permissions-Policy;`.

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

Give that `location` its own `add_header Permissions-Policy "camera=(self), microphone=(self), geolocation=()" always;`. It no longer inherits the server-level headers, so repeat the others there. With `add_header_inherit merge;`, add `add_header_inherit off;` in that location.

### Nginx accepts my header but Chrome ignores it. Why?

Nginx does not check the value. A syntax error, such as an upper-case feature name, spaces around `=` or a trailing comma, makes Chrome drop the whole header and log "Parse of permissions policy failed" in the console.

## Sources

- [Module ngx_http_headers_module: add_header and add_header_inherit](https://nginx.org/en/docs/http/ngx_http_headers_module.html), nginx.org
- [Module ngx_http_proxy_module: proxy_hide_header](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header), nginx.org
- [Module ngx_http_fastcgi_module: fastcgi_hide_header](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_hide_header), nginx.org
- [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
