Direct browser uploads

​

Goal

​

Prerequisites

• A backend route that authenticates the user before creating a session
• A browser File or Blob
• CORS configured on the bucket when the browser origin differs from your app

​

Workflow

​

Server creates the upload URL

const upload = await stackshift.assets.signedUploadUrl({
  bucket: 'avatars',
  key: 'users/user_123.png',
  visibility: 'public',
  expiresIn: '10m',
  maxBytes: 5_000_000,
})

​

Browser uploads the file

await fetch(upload.url, {
  method: upload.method,
  body: file,
  headers: { 'Content-Type': file.type },
})

​

Chunked uploads for large files

const controller = new AbortController()
const asset = await stackshift.assets.uploadWithProgress(file, {
  bucket: 'media',
  key: `uploads/${crypto.randomUUID()}-${file.name}`,
  visibility: 'private',
  fileName: file.name,
  fileSize: file.size,
  mimeType: file.type,
  concurrency: 4,
  retryAttempts: 4,
}, {
  onProgress: ({ percent }) => updateProgress(percent),
  signal: controller.signal,
})

// controller.abort() cancels in-flight work and the upload session.
console.log(asset.id, asset.status)

​

Checksums, limits, and idempotency

• A chunked part must be exactly the expected size (the final part may be smaller) and its SHA-256 must match X-Content-SHA256. A mismatch removes the part and returns a checksum error.
• The account content policy and bucket policy are checked when a session is created and again when the completed asset is committed. MIME allowlists, family-specific byte limits, and max_object_bytes can reject an otherwise valid browser request.
• Send an idempotencyKey when creating a session from a retrying backend. The same key and same canonical request reuse the session; a changed key, size, MIME type, or policy returns a conflict.
• Upload tokens expire and are single-use for single uploads. Treat an expired or used token as a new-session condition, not as a reason to retry the same PUT indefinitely.

​

CORS and browser security

• Configure the bucket’s cors_origins for browser origins that need to PUT directly. allowed_origins is the delivery/origin allowlist used by the Assets policy model.
• Use a server-generated key or a server-approved prefix. Do not let a browser overwrite another user’s key merely because it can request a signed URL.
• The upload URL is not a download URL. After completion, use the asset’s public URL or mint a private signed URL according to the final visibility.

​

Expected result

​

Related guides