CORS Policy for Browser Uploads: S3, R2, Presigned URLs, and ETag

What belongs in a browser upload CORS policy?

A browser upload policy needs to match the actual request that JavaScript sends. For object storage uploads, that usually means a frontend origin, a write method, upload headers, exposed response headers, and a preflight cache duration.

PUT vs POST browser uploads

A presigned PUT upload sends the file body directly to the object URL. A presigned POST upload usually submits form data with a policy, signature, key, and file field. Your CORS policy should include the method your backend generated.

• Use PUT when frontend code calls fetch(url, { method: 'PUT' }).
• Use POST when frontend code submits a form or FormData policy.
• Include HEAD when the app checks object existence or metadata after upload.

Choosing a browser upload architecture

Most modern browser upload flows keep large files away from the application server. The backend creates a short-lived presigned URL or form policy, the browser uploads directly to object storage, and the app stores the resulting key, size, content type, or checksum. CORS is the bridge that lets the browser talk to the storage domain while the app itself remains on another origin.

If uploads are private, generate the signed URL only after checking the current user. If uploads are public assets, still restrict object keys and accepted content types on the backend. CORS should not be treated as the security boundary for who may upload; it is the browser permission layer that must match the signed request.

Upload headers that trigger preflight

Browsers send an OPTIONS preflight when the request is not a simple CORS request. Uploads frequently send headers such as Content-Type, checksum headers, or S3 metadata headers. The bucket policy must allow those headers.

[
  {
    "AllowedOrigins": ["https://app.example.com"],
    "AllowedMethods": ["PUT", "POST", "HEAD"],
    "AllowedHeaders": [
      "Content-Type",
      "x-amz-*"
    ],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

Should browser uploads use wildcard origins?

A wildcard origin is tempting for quick testing, but it is usually too broad for app uploads. Use exact origins for production uploads, especially when the request includes credentials, tenant-specific URLs, or sensitive object keys. Public read assets are a better fit for broader origins.

Credentialed requests and signed URLs

Presigned URL uploads usually do not need browser cookies for the storage request itself. The authorization is in the signed URL or form fields. That means your storage CORS policy often does not need to support credentialed browser requests. Keep cookies on your application API, generate the short-lived upload target there, and let the browser upload to storage without sending app cookies to the storage host.

If a custom worker or gateway does require credentials, avoid wildcard origins and return a specific allowed origin. Credentialed CORS is less forgiving, and a permissive-looking policy can still fail in the browser if the response combines credentials with *.

Why ETag needs ExposeHeaders

After an upload succeeds, many apps read ETag to store the uploaded object hash or confirm the write. The browser hides most response headers from JavaScript unless the CORS policy lists them in ExposeHeaders. If upload succeeds but response.headers.get("ETag") returns null, expose the header.

How to test a browser upload policy

1. Generate the presigned URL from your backend as usual.
2. Open DevTools and run the upload from the browser.
3. Find the OPTIONS request and copy origin, method, and request headers.
4. Paste your policy and those details into the CORS debugger.
5. Apply the suggested fixed config and retest the browser request.

Browser upload CORS checklist

• Origin includes protocol, host, and port.
• Methods include PUT or POST, not only GET.
• AllowedHeaders includes every preflight request header.
• ExposeHeaders includes ETag if the app reads it.
• Wildcard origins are avoided for credentialed or app-specific uploads.
• Localhost origins are included during development.

Browser upload CORS FAQ

Generate and debug in one place

Use the S3/R2 CORS Generator & Debugger to create a starting policy, edit the JSON in Monaco, download provider-specific CLI JSON, and diagnose failed browser uploads from the same page.