Object Storage

Store and retrieve files (images, documents, etc.) using S3-compatible object storage. All objects are user-scoped.

Overview

ezAuth provides a managed file storage layer backed by any S3-compatible service (AWS S3, Backblaze B2, MinIO, etc.). Objects are organized into buckets and scoped to individual users.

Concepts

Bucket — a named container for objects, scoped to your application
Object — a file identified by a key (path), with associated content type and size
User-scoped — every object belongs to a specific user. Objects are uniquely identified by (bucket_id, user_id, key)

Configuration

Set the following environment variables to enable object storage:

Variable	Description
`S3_ENDPOINT_URL`	S3-compatible endpoint (e.g., `https://s3.us-west-004.backblazeb2.com`)
`S3_ACCESS_KEY_ID`	S3 access key
`S3_SECRET_ACCESS_KEY`	S3 secret key
`S3_BUCKET_NAME`	S3 bucket name (the actual S3 bucket, not ezAuth buckets)
`S3_REGION`	S3 region (default: `us-east-1`)
`OBJECT_STORAGE_MAX_OBJECT_BYTES`	Max size per object (default: 50 MB)
`OBJECT_STORAGE_LIMIT_BYTES`	Total storage per app (default: 1 GB)

Buckets

// Create a bucket
const bucket = await ez.buckets.create({ name: 'avatars' })

// List buckets
const { buckets } = await ez.buckets.list()

// Delete a bucket
await ez.buckets.delete(bucket.id)

Uploading Objects

JavaScript (Node.js)

The JavaScript SDK doesn't include bucket object methods directly. Use the REST API:

const response = await fetch(
  `${baseUrl}/v1/buckets/${bucketId}/objects/avatar.png`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${secretKey}`,
      'Content-Type': 'image/png',
    },
    body: imageBuffer,
  }
)

Python

# Upload
ez.buckets.objects.put(
    bucket["id"],
    "avatar.png",
    image_bytes,
    "image/png",
)

# Download
data, content_type = ez.buckets.objects.get(bucket["id"], "avatar.png")

# Delete
ez.buckets.objects.delete(bucket["id"], "avatar.png")

# List objects
result = ez.buckets.objects.list(bucket["id"], limit=50)

Swift

// Upload
let obj = try await ez.buckets.objects.put(
    bucketId: bucket.id,
    key: "avatar.png",
    data: imageData,
    contentType: "image/png"
)

// Download
let (data, contentType) = try await ez.buckets.objects.get(
    bucketId: bucket.id,
    key: "avatar.png"
)

User-Scoped Access

With the secret key, specify user_id to manage objects on behalf of a user. With a publishable key + session, the user is automatically inferred from the JWT.

# Backend: access a specific user's objects
data, ct = ez.buckets.objects.get(
    bucket_id,
    "avatar.png",
    user_id="user-uuid",
)

Storage Limits

Limit	Default	Config Variable
Max object size	50 MB	`OBJECT_STORAGE_MAX_OBJECT_BYTES`
Total storage per app	1 GB	`OBJECT_STORAGE_LIMIT_BYTES`

Check current usage:

const usage = await ez.storage.get()
// { used_bytes: 52428800, limit_bytes: 1073741824, used_percent: 4.88 }