File Upload API guide: architecture, security, and provider selection

Define the upload job before choosing a widget

A production upload begins before the first byte moves. The application identifies the user, decides which operation is allowed, describes acceptable file count and size, and creates a record that can outlive a browser tab. Transfer is only one stage. Validation, processing, export, notification, and reconciliation determine whether the product can safely use the file afterward.

Write a completion contract in product terms. “The request returned 200” is weak; “the original and required derivatives are stored under this tenant, the asset record names their versions, and a duplicate callback changes nothing” is testable. Record which failures users may retry, which require a new upload, and which leave an operator-visible state for recovery.

Choose one of four explicit byte paths

In an application relay, the browser sends the file to your server and your server forwards or stores it. This is understandable and gives the application immediate control, but every byte consumes your ingress, memory or temporary disk, connection time, and egress. It fits small, infrequent files when the existing server can enforce limits and stream safely without buffering entire bodies.

“Direct to cloud” is ambiguous, so name the destination. A browser can upload directly to object storage with short-lived credentials, directly to a processing service such as Transloadit, or ask a service to import an existing remote URL. Direct storage minimizes hops when persistence is the only job. Direct processing keeps the application out of the data path while a workflow validates, transforms, and exports files to owned storage.

Design resumability separately from retries

A retry starts an operation again; a resumable transfer continues an existing upload from a server-confirmed byte offset. With tus, the client retains the upload URL, asks the server for Upload-Offset, and sends only the remaining bytes. Persist that URL outside transient component state if a refresh or crash should recover, and fingerprint files carefully so one user’s local file is never attached to another upload resource.

Resumability does not make time unlimited or processing idempotent. A Transloadit Assembly still has eight hours from creation to finish uploading, and creating a replacement Assembly can duplicate work unless the application reconciles the old identifier. Define how the client handles pause, offline time, expired resources, changed files, abandoned uploads, and a completion response lost after the server accepted the final bytes.

Authorize intent on the server and distrust the bytes

Browser code may contain a public Auth Key, but it must never contain the Transloadit Auth Secret or permanent storage credentials. Authenticate the user in your application, select a saved Template on the server, and return short-lived signed parameters with a unique nonce. Set allow_steps_override to false when the browser has no legitimate reason to replace Steps, because a client-selected Step graph could otherwise change processing or export behavior.

A valid signature proves that the parameter payload was authorized; it does not prove that the uploaded bytes match a filename, extension, declared MIME type, tenant, or moderation policy. Limit request bodies before expensive work, inspect observed file properties, reject unsupported content, scan where the threat model requires it, and keep untrusted output away from public storage until the workflow reaches an approved state.

Separate durable storage from upload processing

An upload endpoint is not automatically a system of record. Decide which bucket or asset database owns the original, how derivatives relate to it, which identifiers survive renames, and who deletes each copy. Transloadit retains temporary results for at least 24 hours, while their access URLs can expire after a few hours. Export files that must persist. Temporary URLs are limited to short-term retrieval, not embedding or repeated product delivery.

Place export inside the Assembly when workflow success requires both processing and persistence. An export Robot can use stored Template Credentials to write results to the chosen destination as part of the workflow. Alternatively, upload directly to owned storage first and invoke processing from a controlled event. That path gains an early durable copy but adds orchestration and another transfer into the processor.

Make the build-versus-buy decision at the ownership boundary

Build the transfer path when requirements are narrow and the team is prepared to own the complete lifecycle. A small authenticated form that streams short files into one existing bucket may not justify another platform. The estimate must still include multipart parsing, backpressure, size enforcement, resumability or its deliberate absence, cleanup, abuse controls, observability, upgrades, and support for failures outside the request’s lifetime.

A managed service becomes more attractive as the workflow combines unreliable networks, large files, browser UX, remote sources, media inspection, transformation, or several storage destinations. Buying does not remove application ownership: tenant checks, authorization, asset records, retention, publication, and incident handling remain yours. A hybrid design often works best, with owned storage and business state around a managed transfer and processing layer.

Compare providers with failure tests, not feature counts

Create a scorecard from the product’s actual workload. Compare browser and mobile clients, open protocol support, maximum file size, concurrency behavior, geographic endpoints, remote imports, processing breadth, storage destinations, credential isolation, webhook verification, status retention, support, and exit options. Mark every feature as required, optional, or irrelevant before looking at vendor pages.

Run the same fixtures through each serious candidate. Interrupt a large upload, reload the page, send a duplicate completion event, revoke storage credentials, decline a file after receipt, exceed a limit, and lose the final response. Measure user-visible recovery, bytes retransmitted, time to durable output, operator evidence, and cleanup. A polished picker says little about these production properties.

Implement a signed Uppy and Transloadit upload

The browser example lets Uppy manage selection and tus transfer while the Transloadit plugin requests Assembly parameters from your application. The server endpoint must authenticate the current user before returning the object from calcSignature. It should select the Template itself instead of accepting arbitrary Steps or a caller-provided storage destination, and it should rate-limit authorization independently from upload traffic.

Before using this example, enable “Require a correct Signature” in Workspace Settings, save the Template below, and set its ID in the server’s TRANSLOADIT_UPLOAD_TEMPLATE_ID. Store AWS access to your own private bucket as Template Credentials named my_s3_credentials. The Auth Key may reach the browser; the Auth Secret and AWS credentials must not. The signing endpoint must return Cache-Control: no-store so each authorized operation receives fresh parameters.

Install @uppy/core, @uppy/dashboard, and @uppy/transloadit in the frontend and the transloadit Node SDK on the server. Mount the browser example after an element such as <div id="photo-upload"></div> exists. Implement /api/transloadit-params in your framework with session authentication and upload authorization before calling the signing helper. Reject unauthenticated or unauthorized requests; the helper itself is not an authentication endpoint.

The example permits one JPEG, PNG, or WebP image up to 10 MiB. Uppy’s restrictions provide immediate feedback, while the signed auth.max_size and auth.max_number_of_files limits and the Template’s server-side filter enforce the policy. waitForEncoding: true waits for the Assembly, including export, instead of treating transfer completion as workflow completion.

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Transloadit from '@uppy/transloadit'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

// Mount this once after <div id="photo-upload"></div> exists in your page.
const uppy = new Uppy({
  restrictions: {
    maxNumberOfFiles: 1,
    maxFileSize: 10 * 1024 * 1024,
    allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
  },
}).use(Dashboard, { inline: true, target: '#photo-upload' }).use(Transloadit, {
  async assemblyOptions() {
    const response = await fetch('/api/transloadit-params', {
      credentials: 'same-origin',
      cache: 'no-store',
    })
    if (!response.ok) {
      throw new Error('Could not authorize this upload')
    }
    return response.json()
  },
  waitForEncoding: true,
  retryDelays: [0, 1000, 3000, 5000, 10000],
})

uppy.on('transloadit:assembly-created', (assembly) => {
  // Associate this ID with the server-side operation before the user leaves the page.
  console.log('Assembly started:', assembly.assembly_id)
})

uppy.on('transloadit:complete', (assembly) => {
  // Record completion against the ID persisted at transloadit:assembly-created.
  console.log('Processing completed. Assembly:', assembly.assembly_id)
})

uppy.on('transloadit:assembly-error', () => {
  // Show this through the application’s accessible status UI, not raw API errors or URLs.
  console.error('Processing failed. Check the Assembly in your workspace.')
})

uppy.on('upload-error', () => {
  // Transloadit API signature rejections and Assembly errors also reach this event.
  // Failures thrown by assemblyOptions() use Uppy’s general error event instead.
  // Deduplicate application notices.
  console.error('The upload workflow failed. Check its status before retrying.')
})

import { randomUUID } from 'node:crypto'
import { Transloadit } from 'transloadit'

function requiredEnvironmentValue(name: string): string {
  const value = process.env[name]
  if (value == null) throw new Error(`Missing environment variable: ${name}`)
  return value
}

const transloadit = new Transloadit({
  authKey: requiredEnvironmentValue('TRANSLOADIT_KEY'),
  authSecret: requiredEnvironmentValue('TRANSLOADIT_SECRET'),
})

export function createAuthorizedUploadParameters(): { params: string; signature: string } {
  // Call this only after the server has authenticated the request and authorized the operation.
  const params = {
    auth: {
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      max_size: 10 * 1024 * 1024,
      max_number_of_files: 1,
      nonce: randomUUID(),
    },
    template_id: requiredEnvironmentValue('TRANSLOADIT_UPLOAD_TEMPLATE_ID'),
  }
  return transloadit.calcSignature(params)
}

Connect intake, validation, processing, and export

One Assembly connects the complete path: authenticated Uppy upload → /file/filter validation → /image/resize processing → /s3/store export to a customer-owned bucket. Its saved Template supplies the workflow, and each use dependency determines which files reach the next Step. Uppy supplies the upload experience; Transloadit executes the managed workflow, not your application server.

The filter checks detected MIME type and file size, then passes only accepted images to the preview and export Steps. error_on_decline: true makes a rejection an Assembly error. MIME and size checks are not malware scanning or content moderation; add those Steps before processing and export when your policy requires them.

Use a private S3 bucket with Block Public Access enabled and appropriately scoped Template Credentials. acl: "bucket-default" omits an object ACL and relies on the bucket’s access policy; it does not make a public bucket private. The export stores the accepted original and a preview bounded by 1600 × 1600 pixels under Assembly- and file-specific paths. Neither export reads directly from unfiltered :original.

{
  "allow_steps_override": false,
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^image/(jpeg|png|webp)$"]
      ],
      "declines": [["${file.size}", ">", 10485760]],
      "error_on_decline": true
    },
    "preview": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 1600,
      "height": 1600
    },
    "exported": {
      "use": ["accepted_images", "preview"],
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "acl": "bucket-default",
      "path": "uploads/${assembly.id}/${file.id}/${file.url_name}"
    }
  }
}

Test a large video from interrupted upload to private export

For a video workflow, create a Template Credential named large-upload-output using IAM credentials whose s3:PutObject permission is limited to the private upload-tests/ prefix. Follow the /s3/store IAM setup for bucket-level s3:ListBucket and s3:GetBucketLocation permissions; the location lookup is unnecessary when the Template Credential supplies bucket_region. Replace YOUR_AUTH_KEY with the workspace’s Auth Key (not its Auth Secret), save the Template below, and require Signature Authentication on that Template. Use a private bucket with Block Public Access enabled and Object Ownership set to Bucket owner enforced. The acl: "bucket-default" setting omits an object ACL; access remains controlled by your bucket and IAM policies. Set the authenticated signing endpoint’s TRANSLOADIT_UPLOAD_TEMPLATE_ID to this saved video Template’s ID for the test. Reuse the Uppy integration above with a user-selected file and one Uppy instance. The Template’s 256 MiB and one-file limits are example policy. Mirror those limits in the Uppy core restrictions option (maxFileSize, maxNumberOfFiles) for early picker feedback; server-side checks remain necessary. For this video test, replace the image-only restriction with allowedFileTypes: ["video/*"] and set both the browser’s maxFileSize and the signed auth.max_size to 256 * 1024 * 1024; keep both file-count limits at 1. Check your workspace’s upload limits and supported source formats before testing. The Template detects a video MIME family, creates a bounded MP4 rendition, and exports that rendition and the accepted original. This is not a complete malware or content-safety policy.

Transfer completion is not the finish line. With waitForEncoding: true, the browser waits for processing, but your application still needs a durable Assembly ID and verified notifications or an Assembly Status lookup if the tab disappears. An export failure must not mark the asset ready. Confirm ASSEMBLY_COMPLETED, the required rendition, and both private S3 objects; compare the exported original’s checksum with the input before recording success. These private objects are not automatically public playback URLs.

Run three online controls and three interrupted runs using the same owned 100–200 MiB video. Record the exact file bytes and SHA-256, duration and codecs, browser and package versions, Template, region, plan, and network setup. In Chrome DevTools, apply a custom throttling profile and record its settings, switch to Offline near 25% uploaded for 10 seconds, and restore the profile without reloading. For network failures reported while the browser is offline and retry attempts remain, the installed Uppy tus plugin pauses its queue until an online event. Each retry still consumes an attempt; upload progress can reset the counter. The sum of retryDelays is not an offline time limit. Verify that a HEAD request reports the saved Upload-Offset and subsequent PATCH requests continue the same tus resource. This exercises an emulated browser interruption, not server failover or every network condition.

Measure from upload initiation to the first completed Assembly with verified exported objects, not just to the last uploaded byte. Also record reconnect-to-completion time, retransmitted bytes where observable, failures, duplicate Assemblies, and the raw run count. This is a reproducible test procedure, not a published benchmark result. Bounded retries can be exhausted by repeated request failures, the eight-hour Assembly upload deadline still applies, and this in-memory example does not restore state after a reload or closed tab. Test cancellation, expired authorization, over-limit files, and revoked export credentials separately. See the resumable-upload API for the protocol handoff and the video and S3 demo for a processing and public-export example.

{
  "allow_steps_override": false,
  "auth": {
    "key": "YOUR_AUTH_KEY",
    "max_size": 268435456,
    "max_number_of_files": 1
  },
  "steps": {
    ":original": { "robot": "/upload/handle" },
    "accepted_video": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^video/"]],
      "error_on_decline": true
    },
    "rendition": {
      "use": "accepted_video",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/mp4/360p",
      "width": 640,
      "height": 360,
      "resize_strategy": "fit",
      "result": true
    },
    "exported": {
      "use": ["accepted_video", "rendition"],
      "robot": "/s3/store",
      "credentials": "large-upload-output",
      "acl": "bucket-default",
      "path": "upload-tests/${assembly.id}/${file.id}/${file.url_name}"
    }
  }
}