How to set a custom referrer in cURL

Some HTTP endpoints vary behavior based on the page or workflow that appears to have sent the request. Setting a custom Referer header in cURL lets you reproduce browser-style navigation, test origin-sensitive application flows, and confirm exactly what a server receives before you debug the application itself.

HTTP keeps the historical Referer spelling, so cURL exposes the option as --referer or -e. This purpose-built flag sets the request header directly and, unlike a raw --header 'Referer: ...' override, also supports ;auto so followed redirects can update the header to the previous URL automatically.

Treat referrer testing as request metadata verification, not as an access-control bypass. Some services use the header for analytics, CSRF heuristics, or navigation-dependent behavior, while others ignore it completely. Use a safe echo endpoint or verbose logging to confirm what left the client, add --disable first when a local ~/.curlrc might otherwise inject defaults, and keep published examples masked even when live verification uses a real endpoint.

1. Send a request with --referer to confirm that the target receives the expected Referer value.

   $ curl --disable --silent --show-error \
     --referer 'https://portal.example.net/account/sign-in' \
     https://api.example.net/v1/request-inspect
   {
     "method": "GET",
     "url": "https://api.example.net/v1/request-inspect",
     "headers": {
       "Host": [
         "api.example.net"
       ],
       "Referer": [
         "https://portal.example.net/account/sign-in"
       ],
       "User-Agent": [
         "curl/8.7.1"
       ]
     }
   }

   Success is visible when the echoed request headers include the exact Referer URL that you passed on the command line.

2. Inspect the outbound request headers with --verbose when you need client-side proof before tracing the server path.

   $ curl --disable --silent --show-error --verbose \
     --output /dev/null \
     --referer 'https://portal.example.net/account/sign-in' \
     https://api.example.net/v1/request-inspect 2>&1 | grep -E '^> (GET|Host:|User-Agent:|Accept:|Referer:)'
   > GET /v1/request-inspect HTTP/2
   > Host: api.example.net
   > User-Agent: curl/8.7.1
   > Accept: */*
   > Referer: https://portal.example.net/account/sign-in

   The > lines are the headers that cURL sent on the wire, which makes this the fastest local verification step before checking upstream logs.

   Related: How to view HTTP request headers in cURL

3. Pass an empty string when the request should go out without any Referer header.

   $ curl --disable --silent --show-error \
     --referer '' \
     https://api.example.net/v1/request-inspect
   {
     "method": "GET",
     "url": "https://api.example.net/v1/request-inspect",
     "headers": {
       "Host": [
         "api.example.net"
       ],
       "User-Agent": [
         "curl/8.7.1"
       ]
     }
   }

   In current curl testing, --referer '' removed the header entirely rather than sending an empty Referer: line. If the target workflow depends on a literally blank header value, verify that case separately.

4. Add ;auto with --location when followed redirects should update the Referer header to the previous URL automatically.

   $ curl --disable --silent --show-error --location \
     --referer ';auto' \
     --output /dev/null \
     --write-out 'final=%{url_effective}\nreferer=%{referer}\nredirects=%{num_redirects}\n' \
     'https://edge.example.net/redirects/request-inspect'
   final=https://api.example.net/v1/request-inspect
   referer=https://edge.example.net/redirects/request-inspect
   redirects=1

   The referer write-out value shows that the followed request used the redirecting URL as its Referer.

   Related: How to follow HTTP redirects with cURL

5. Seed the first hop with an explicit page and still let redirects update the later requests automatically.

   $ curl --disable --silent --show-error --location --verbose \
     --output /dev/null \
     --referer 'https://portal.example.net/account/sign-in;auto' \
     'https://edge.example.net/redirects/request-inspect' 2>&1 | grep -E '^> GET|^> Referer:|^\\* Issue another request'
   > GET /redirects/request-inspect HTTP/2
   > Referer: https://portal.example.net/account/sign-in
   * Issue another request to this URL: 'https://api.example.net/v1/request-inspect'
   > GET /v1/request-inspect HTTP/2
   > Referer: https://edge.example.net/redirects/request-inspect

   The first request keeps the explicit starting page, and the followed request switches to the redirecting URL automatically.