Content-Disposition tells an HTTP client how response content is intended to be presented, including inline display or attachment handling and a suggested filename. It is useful for downloads, but it does not authorize access, prove that content is safe, or guarantee identical behavior across every browser and client.
A well-designed download path combines appropriate headers with controlled names, content handling, and authorization. This guide explains the boundary between presentation metadata and actual security so a convenient filename feature does not become an unreviewed input path.
Separate access from presentation
Authorize the request before returning private content. A response marked attachment is still a response containing the data. The header does not make an unauthorized download harmless or stop a direct client from reading it.
Map the requested business object to its approved storage location through server-controlled logic. Do not interpret a user-supplied download name as a filesystem path. Object access and suggested filename are separate inputs with separate validation requirements.
Review tenant and account boundaries. A predictable file identifier is not proof of ownership, and a browser’s save dialog does not provide an application permission check. Test denied requests without returning private content.
Understand inline and attachment intent
Inline indicates ordinary presentation behavior, while attachment suggests download handling. Client behavior also depends on content type, browser features, and the context in which the response is used. Treat the header as part of a supported presentation contract.
Use the behavior that fits the product. A document intended for preview can require a different path from an untrusted file intended only for download. Do not force all content through one generic route without reviewing the implications.
If the application serves potentially active content, evaluate isolation, content type, and related browser controls separately. Attachment handling is not a complete defense against every way a file can be opened or reused.
Construct headers through supported APIs
Use the framework’s supported response or download helper when possible. It can handle syntax and encoding details more reliably than ad hoc string concatenation. Review what the helper does with supplied filenames and which inputs it permits.
Do not include raw user input containing header delimiters or control characters. Validate and encode according to the framework and HTTP requirements. A display name from a database can still be untrusted if users or external services originally supplied it.
A simple illustrative response field is:
Content-Disposition: attachment; filename="report.csv"This uses a controlled ASCII name and illustrates presentation syntax. It is not a complete response and does not establish access, caching, or content correctness.
Choose filenames that are safe and useful
Generate or normalize a suggested name according to an explicit product policy. Remove path semantics and unsupported characters as appropriate, and avoid exposing internal storage keys or private identifiers unnecessarily.
Keep file extensions consistent with the approved content representation. A misleading extension can confuse users and downstream tools. The suggested name is not proof of file type, so clients and the application should not rely on it as the only validation.
Consider length, reserved names, duplicate downloads, and operating-system differences. A name valid in one environment may behave differently elsewhere. Test the actual supported client set rather than inventing one universal filesystem rule.
Handle international names deliberately
HTTP defines filename-related parameter forms for compatibility and encoding, including filename and filename*. MDN describes their behavior and recommendations. Use the framework’s supported mechanism for non-ASCII names instead of manually combining encodings.
Where a compatible fallback is needed, make it a sensible controlled name. Avoid relying on percent-escape behavior in a plain filename parameter across all browsers. Keep the intended decoded result in the test plan.
Internationalization is a usability requirement, not a reason to accept arbitrary header syntax. Validate the original display name and verify the final emitted header through the real response stack.
Align content type and caching policy
Return the correct Content-Type for the approved representation. Review content-sniffing controls and application isolation where relevant. A filename ending in a particular extension does not change the bytes or establish safe browser interpretation.
Choose caching policy according to sensitivity and product behavior. Private exports can contain information that should not be retained in a shared cache. Content-Disposition does not provide that cache boundary, so configure and test it separately.
Protect logs and analytics. Download URLs, object identifiers, and suggested names can expose private information. Record useful operational outcomes without dumping signed URLs, full response bodies, or unnecessarily identifying filenames into broad telemetry.
Test actual clients and response paths
Inspect the final headers after proxies, storage gateways, or CDN behavior. A backend setting can be altered by another component. Test the route the user actually receives rather than only a unit-level response object.
Verify ordinary ASCII names, approved international names, long names, and rejected invalid input using synthetic data. Check both navigation-based downloads and programmatic clients if the product supports them. Record which behavior is guaranteed by the product and which remains client-dependent.
Test authorization failures and error responses. An error should not be saved under the expected report name as if it were a successful export without the client noticing. Use appropriate status handling and validate the returned content where the workflow requires it.
A practical private-report endpoint
Suppose a signed-in user downloads a generated report. The backend verifies ownership, retrieves the approved object, emits the correct type and controlled attachment name, and applies the reviewed private-cache policy. The filename is derived from nonsecret product context rather than the raw storage path.
A test client confirms the report bytes, name behavior, and rejection of another user’s record. A browser test checks supported international names. These checks demonstrate more than the presence of a single header.
Document filename policy, supported clients, access rules, and content handling. Presentation metadata should make a download predictable without becoming the source of its security claims.
Frequently asked questions
Does attachment make a file safe or private?
No. It expresses presentation intent. Authorization, content safety, and caching need separate controls.
Can I concatenate any supplied name into the header?
No. Use supported framework behavior and validate the input according to the intended filename policy.
Where can I check parameter syntax?
Read MDN’s Content-Disposition reference. For private response retention separately, see our Cache-Control guide.
