Your web app can't read a header your API sends? Expose it
Short answer: When your web app calls an API on a different origin, the browser only lets JavaScript read a short list of "safe" response headers. Everything else comes back as null in your code, even though you can see it in the browser's network tab. To make a header readable, the API must list it in an Access-Control-Expose-Headers response header, for example Access-Control-Expose-Headers: Content-Disposition, X-Total-Count. If your requests send cookies or other credentials, list each header by name rather than using *.
The confusing symptom
You add a header to your API, perhaps the total number of results for pagination, the filename for a download, a request ID for support tickets, or rate-limit information. You check the browser's developer tools and the header is there. But in your code:
response.headers.get('X-Total-Count') returns null.
Nothing is wrong with your API or your code. The browser is applying CORS rules.
Why the browser hides it
Cross-Origin Resource Sharing (CORS) controls what a page on one origin can read from another. Your frontend at app.example.com.au calling api.example.com.au counts as cross-origin, because the hostnames differ. So does a different port during development, like localhost:5173 calling localhost:8080.
MDN's documentation for Access-Control-Expose-Headers explains that only the CORS-safelisted response headers are exposed to scripts by default. Those are:
Cache-ControlContent-LanguageContent-LengthContent-TypeExpiresLast-ModifiedPragma
Anything else, including Content-Disposition, ETag, Location, Link and every X- header you invent, is hidden from JavaScript unless the server says otherwise.
Developer tools show you the raw network traffic, which is why the header looks present. Your page's JavaScript gets a filtered view.
The fix: expose the headers you need
Add Access-Control-Expose-Headers to the API's responses, listing the headers your frontend should read:
Access-Control-Expose-Headers: Content-Disposition, X-Total-Count, X-Request-Id
Most frameworks' CORS settings have an "exposed headers" option, so you rarely need to set it by hand. Look for a setting with "expose" in its name in your CORS middleware, API gateway or serverless platform.
Things to get right:
- Put it on the actual response, not only on the preflight
OPTIONSresponse. The browser checks it on the response your code reads. - List each header your code reads. Header names aren't case-sensitive.
- Avoid exposing sensitive headers you don't need. Only list what the frontend uses.
The wildcard and credentials
MDN notes that Access-Control-Expose-Headers: * exposes every header, but only for requests without credentials, meaning without cookies or HTTP authentication. For requests with credentials, * is treated as a literal header name, so nothing useful is exposed. MDN's CORS guide makes the same point: with credentialed requests, the server must give an explicit list.
If your app logs in with cookies and calls the API with credentials: 'include', use the explicit list.
Common headers people hit this with
Download filenames
Your API generates a PDF invoice and sends Content-Disposition: attachment; filename="invoice-1042.pdf". Your frontend wants the filename to save the file with the right name, but gets null. Expose Content-Disposition.
Pagination totals and links
APIs that return the total count or next-page link in headers, such as X-Total-Count or Link, need those exposed for your table or infinite list to work.
Request IDs
A request ID in a response header is useful to show in error messages ("quote this code to support"). Expose it so your frontend can display it.
Rate limits
If you show users how many requests or exports they have left, the rate-limit headers must be exposed.
Location after creating a record
When a POST returns 201 Created with a Location header pointing to the new record, expose Location if the frontend needs to navigate there.
An alternative: avoid cross-origin calls
If your frontend and API are served from the same origin, for example the API under /api on the same domain through a reverse proxy, CORS doesn't apply and every header is readable. That also removes preflight requests. It's often the simplest setup for a small app, though it depends on your hosting.
Another option is to move the information into the response body, such as returning { items: [...], total: 120 }. That sidesteps the issue, at the cost of changing your API's shape.
Same fix, different layers
If your API sits behind a gateway, a serverless platform or a CDN that adds CORS headers itself, the exposed list may need setting there instead of, or as well as, in your application. When two layers both set CORS headers, browsers can receive duplicates and reject the response. Decide which layer owns CORS and configure it in one place.
Checking it works
- In the network tab, select the response and confirm
Access-Control-Expose-Headerslists your header. - In the console, run your fetch and log
response.headers.get('Your-Header'). - Test with the same credentials mode your app uses in production.
- If you have a CDN or gateway in front of the API, check it isn't stripping or overriding CORS headers.
A worked example
An illustrative Perth furniture marketplace built an order history page that downloads invoices from its API on a separate subdomain. Files saved as "download" with no extension, because the frontend couldn't read the filename. The developer saw Content-Disposition in the network tab and assumed a code bug. Adding Content-Disposition and X-Request-Id to the exposed headers in the API's CORS settings fixed both the filenames and the support codes on the error screen.
FAQ
Why does it work in Postman or curl?
Those tools don't enforce browser CORS rules, so they show every header.
Do I need this for same-origin requests?
No. It only applies when the page and API are on different origins.
Does exposing a header create a security risk?
Only if the header contains something the page shouldn't see. Expose just what your frontend needs.
Is this related to Access-Control-Allow-Headers?
That one controls which request headers the browser may send. Expose-Headers controls which response headers scripts may read.
If your frontend can't read data your API sends, tell us how the two are hosted and we'll help you sort out the CORS settings.