Skip to main content

Uploads and signed URLs

tc.storage works the same in the browser, in server code (as the request's person) and in jobs (as the app). Every call returns { data, error }; error.code names the problem and error.fix says what to do.

Upload​

import { tc } from '@tenantcloud/sdk'

const me = await tc.auth.user()
const path = `${me.id}/${crypto.randomUUID()}-${file.name}` // keep people's files under their id

const { data, error } = await tc.storage.from('receipts').upload(path, file)
// data: { path, size, contentType }
if (error) alert(error.message) // e.g. STORAGE_QUOTA_EXCEEDED
  • In the browser, pass a File or Blob, for example from an <input type="file"> or a drop.
  • On the server, pass a Buffer, string, Blob or Node stream, and the request: tc.storage.from('receipts', { request: req }) (or use tc.middleware()).
  • Options: { contentType, upsert }. Without upsert: true, uploading to an existing path fails with STORAGE_EXISTS, so nothing is overwritten by accident. Only the uploader (or an editor/admin) can replace a file.

Uploads are streamed: nothing is buffered in full, and the size limits are enforced while streaming, so nothing is stored past a limit.

Download, list and delete​

const { data: blob } = await tc.storage.from('receipts').download(path)

const { data: files } = await tc.storage.from('receipts').list(me.id)
// [{ name, path, owner, metadata: { size, mimetype } }]; folders have id null

await tc.storage.from('receipts').remove([path])

const { data: buckets } = await tc.storage.listBuckets()

Downloads support HTTP Range requests (206) and ETag caching (304). Listings return up to 1,000 entries per folder page by default. In private buckets, listings hide other people's files.

Signed URLs​

A signed URL lets someone read one file they otherwise couldn't, for example an approver opening a requester's receipt in a bucket without readRoles, or an <img> thumbnail.

const { data } = await tc.storage.from('receipts').createSignedUrl(path, 300) // seconds
// <img src={data.signedUrl}>

const { data: many } = await tc.storage.from('receipts').createSignedUrls([a, b, c], 300)
PropertyDetail
WhereOn the app's own origin
LifetimeDefault 1 hour, at most 7 days
What it liftsThe ownership rule only. The person opening it must still be signed in and allowed to open the app
SigningHMAC-SHA256 with a per-project key
After expirySTORAGE_SIGNATURE_EXPIRED
tip

Store the file's path in your table (for example a receipt_path text column), not a URL. Links expire; sign when you show the file.

Public URLs in app-public buckets​

const url = tc.storage.from('exports').getPublicUrl('q3/report.pdf').data.publicUrl

getPublicUrl only works for app-public buckets (STORAGE_NOT_PUBLIC otherwise). "Public" means everyone who can open the app, never the internet.

Python​

from tenantcloud import tc

tc.storage.from_("receipts").upload(path, data, content_type="application/pdf", request=request)
data = tc.storage.from_("receipts").download(path, request=request) # bytes
files = tc.storage.from_("receipts").list("folder", request=request)
tc.storage.from_("receipts").remove([path], request=request)
link = tc.storage.from_("receipts").create_signed_url(path, 300, request=request) # {"signedUrl": ...}

Pass request= in web handlers so the call acts as the signed-in person; jobs omit it and act as the app. Python raises TcError instead of returning { error }.

CLI​

tc storage buckets # buckets, usage and quota
tc storage buckets create exports --visibility app-public
tc storage buckets create receipts --read-role approver
tc storage put ./report.pdf exports/q3/report.pdf # streamed; --upsert, --content-type
tc storage ls exports/q3
tc storage get exports/q3/report.pdf ./report.pdf
tc storage rm exports/q3/report.pdf
tc storage sign exports/q3/report.pdf --expires 600

HTTP​

The SDK calls these on the app's origin:

Method and pathDoes
POST /_tc/storage/v1/object/<bucket>/<path>Upload (header x-upsert: true to replace)
PUT /_tc/storage/v1/object/<bucket>/<path>Upload or replace
GET /_tc/storage/v1/object/<bucket>/<path>Download
DELETE /_tc/storage/v1/object/<bucket>/<path>Delete one file
DELETE /_tc/storage/v1/object/<bucket>Delete several files
GET /_tc/storage/v1/object/list/<bucket>List a folder
POST /_tc/storage/v1/object/sign/<bucket>/<path>Create a signed URL
POST /_tc/storage/v1/object/sign/<bucket>Create several signed URLs
GET /_tc/storage/v1/object/public/<bucket>/<path>Read from an app-public bucket
GET /_tc/storage/v1/bucketsList buckets
GET /_tc/storage/v1/usageUsage and quota

Error codes​

Storage calls fail with a STORAGE_* code and a fix hint. The full list, with fixes, is in the SDK storage reference; codes from every service are in the error code reference.

Was this page helpful?