Headers and Basic Authentication

You can configure custom headers and basic auth for your Netlify site by adding a _headers file to the root of your site folder.

Note that if you’re running a build command or site generator, the _headers file should end up in the folder you’re deploying. Some generators, like Jekyll, may also require additional configuration to avoid exclusion of files that begin with _. (For Jekyll, this requires adding an include parameter to _config.yml.)

Custom headers

The format is very simple. You can specify one or several URL paths with their additional headers:

## A path:
  # Headers for that path:
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block
  X-Frame-Options: SAMEORIGIN

Paths can contain * or :placeholders. A :placeholder matches anything except / while a * matches anything.

Here’s an example of settings the X-Frame-Options and X-XSS-Protection headers for all pages on your site:

  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block

Basic auth

This feature may not be available on all plans.

The headers file can also be used to set basic authentication headers. It’s a simple way to limit access to particular parts of your site.

  Basic-Auth: someuser:somepassword anotheruser:anotherpassword

This will trigger the built-in basic browser authentication for any URL under /something. There are two users defined here: one with the username “someuser” and password “somepassword”, the other with “anotheruser” and “anotherpassword”.

Unlike other headers in the _headers file, the Basic-Auth header will obviously not be sent as a standard HTTP header but used to control the appropriate HTTP headers for basic authentication.

If Visitor Access Control is also enabled, the Visitor Access Control password will be asked for after the Basic-Auth login prompt.

Multi-key header rules

The _headers file can include multiple headers with the same name. In that case, Netlify, will concatenate the values of those headers into a single header as described in the RFC 7230.

For example, you can include several cache-control header fields in the file, like this:

  cache-control: max-age=0
  cache-control: no-cache
  cache-control: no-store
  cache-control: must-revalidate

And they will be collapsed into one header following the HTTP 1.1 specification:

cache-control: max-age=0,no-cache,no-store,must-revalidate

Structured configuration

You can also specify header rules in your netlify.toml file. You can create this file in the root directory of your Git repository, if you don’t have one already. We use TOML’s array of tables to specify each individual header rule. You can see the list of valid keywords for each rule below:

  • for: The path or URL where the headers will be added.
  • values: A map of values to add to the response headers.

You can see a full example here:

  for = "/*"
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"

    # COMMENT: Multi-key header rules are expressed with multi-line strings
	cache-control = '''

Notice something is incorrect or outdated?

First off, great catch! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.

Want to have a conversation?

Visit the Netlify Community to discuss ideas and questions with your fellow Netlify users.

Want to get started quick?