Serverpod File Uploads

Server: create upload description

Future<String> getUploadDescription(Session session, String path) async {
  return await session.storage.createUploadDescription(
    storageId: 'public',
    path: path,
  );
}

Server: verify upload

Future<bool> verifyUpload(Session session, String path) async {
  return await session.storage.verifyUpload(
    storageId: 'public', path: path);
}

Client: upload

var desc = await client.myEndpoint.getUploadDescription('profile/$userId/avatar.png');
var uploader = FileUploader(desc);
await uploader.upload(byteDataOrStream);
await client.myEndpoint.verifyUpload('profile/$userId/avatar.png');

Stream

Security checklist

• Require authentication/authorization for both description and verification endpoints.
• Validate or derive content type, size, and extension before issuing descriptions.
• Never let clients choose cross-tenant paths or storage IDs.
• Store metadata in your database after

  verifyUpload

  succeeds.

Accessing stored files

• session.storage.fileExists(storageId: 'public', path: path)

• session.storage.publicDownloadUrl(storageId: 'public', path: path)

  (public storage only)

• session.storage.temporaryDownloadUrl(storageId: 'private', path: path)

  (time-limited access to private files)

• session.storage.retrieveFile(storageId: 'public', path: path)

Storage backends

• Database (default):

  public

  and

  private

  storages. Fine for dev.
• Google Cloud Storage: Add

  serverpod_cloud_storage_gcp

  , set HMAC keys in

  passwords.yaml

  or env. Register:

  pod.addCloudStorage(GoogleCloudStorage(...))

  .
• AWS S3: Add

  serverpod_cloud_storage_s3

  , set AWS keys. Register:

  pod.addCloudStorage(S3CloudStorage(...))

  .
• S3-compatible/R2: Use the matching integration package when targeting compatible providers.

storageId: 'public'

'private'