Secure File Upload APIs: Validation and Isolation

Write a policy before adding multipart

API file upload security begins with a business decision: which users may upload, what the file is for, and which types and sizes are necessary. A profile photo endpoint and a legal document archive need different rules. Specify accepted formats, per-file and per-account limits, storage lifetime, and who may later download the result. Reject files that do not serve the stated purpose instead of accepting every media type and trying to make it safe afterward.

Document the request body, maximum practical size, authentication, and possible errors in OpenAPI. A client-provided Content-Type or extension is a hint, not proof of a file's contents. Test the actual bytes and use a parser appropriate to the allowed format. Be cautious with polyglot files and complex office documents, which may contain active content despite an apparently familiar extension.

Validate at more than one layer

Reject obviously invalid requests before storing large bodies when infrastructure supports it, then enforce size and format again in the application. Use an allowlist of extensions and MIME types appropriate to the business need. Inspect file signatures where useful, but do not rely on magic bytes alone: many formats can embed unexpected structures. Limit decompressed size and archive depth to avoid a small upload expanding into excessive work.

Give each uploaded object a server-generated identifier. Never trust the client filename as a filesystem path or public URL. Remove path separators and control characters from any display name that you retain. Keep the original name only if users need it, and encode it safely in download headers. An attacker should not be able to overwrite another user's file by choosing the same name.

Isolate storage and processing

Store uploads outside executable application directories and do not let the web server run uploaded content. Use a private object bucket or isolated storage area with access controlled by the application. Process files with a low-privilege worker, limited CPU, memory, time, and network access. A vulnerable image or document parser should not gain access to service credentials or internal metadata endpoints.

Scan for malware when the file type and risk justify it, and define what happens if the scanner is unavailable. Quarantine files until required checks finish. Treat “clean” as one signal, not a guarantee that a parser cannot be exploited. If you transform images or PDFs, consider producing a fresh output file and serving that instead of the original bytes. Audit the transformation path for resource exhaustion.

Make downloads a separate authorization decision

An opaque object key does not replace an access check. Before returning a file, verify that the caller can access the owning record and that the file's state permits download. Apply the same rule to thumbnails, converted versions, signed URLs, and export bundles. Test a second tenant's token against a known file ID and an old share link.

Set a suitable Content-Type and Content-Disposition when serving untrusted content. For files intended only as attachments, avoid inline browser execution. Expiring signed URLs can reduce application traffic, but choose a short lifetime and ensure the URL is bound to the intended object. Revoke or rotate sharing mechanisms when permissions change; a cached public copy may persist after the application denies access.

Bound cost and abuse

Enforce total storage quotas, concurrency limits, and per-user upload rates. Consider the entire workflow: temporary chunks, retries, virus scanning, conversion, and abandoned multipart sessions can consume far more space than the final file. Clean up incomplete objects after a defined interval and monitor queue age. A 429 can slow bursts, while a strict per-file maximum limits the cost of a single request.

Return clear errors for unsupported type, too-large body, pending processing, and failed processing without exposing internal paths or scanner signatures. Decide whether a failed upload is retained for investigation and who may inspect it. Log actor, object ID, size, policy outcome, and correlation ID; avoid logging document contents or download tokens.

Test a realistic upload matrix

Try the smallest valid file, maximum permitted file, wrong extension, mismatched MIME type, corrupt document, nested archive, duplicate filename, and interrupted transfer. Test an authenticated user without permission to attach a file to another tenant's record. Verify that a quarantined or rejected object is not downloadable through an alternate path.

APISAST can review a contract for request size constraints and other documented design signals. It cannot inspect file bytes, malware scanning, bucket permissions, or a conversion worker. Use the specification to make policy reviewable, then run upload and download tests against the actual service. Keep the controls proportionate to the type of file and the consequences of misuse.

Example: profile photo processing

A profile photo endpoint can accept a small set of image formats, enforce a byte limit, decode the image with a maintained library in an isolated worker, and produce a fresh thumbnail. The public API returns an opaque upload ID and a pending state until processing finishes. A client does not receive a stable public URL for the unreviewed original.

Test a valid image, a corrupt image, an image with misleading extension, a huge pixel dimension, and a request to attach the photo to another user's profile. Verify that rejection leaves no accessible object and that a successful thumbnail is served with the intended content type. The worker should have no access to unrelated credentials or private buckets. This pattern gives clear points to measure and troubleshoot. Check that old thumbnails expire when a user replaces or deletes the photo, including copies held by a content delivery network. Otherwise a deleted image may remain reachable through a stale URL.

Continue the work

Use these guides to put the checks into your API review process:

• Design upload errors safely
• Bound repeated uploads
• Review the upload contract

Primary reference: OWASP File Upload Cheat Sheet.

APISAST reviews OpenAPI and Swagger contracts for documented design signals. Confirm authorization, enforcement, performance, and abuse controls against a running service.