​
Public & Private Buckets

SparkDB buckets can be public (world-readable) or private (authenticated access only). Choose the right visibility for your use case.

​
Visibility Overview

SettingAccessUse Case
Private (default)Owner only via API keyUser uploads, backups, sensitive data
PublicAnyone with the URLStatic assets, public downloads, CDN

​
Private Buckets

Private buckets restrict access to the bucket owner. All operations require authentication:
  • Listing files: API key required
  • Uploading: API key required
  • Downloading: API key required (x-api-key header or Authorization: Bearer spk_*)
  • Deleting: API key required
File URLs for private buckets are proxied through the SparkDB API: 
https://api.sparkdb.pro/buckets/{bucketId}/files/{filename}
This ensures files are only accessible to authenticated users.

​
When to Use Private

  • User-generated content (profile pictures, document uploads)
  • Backups and data exports
  • Any content that should not be publicly accessible

​
Public Buckets

Public buckets allow anyone with the file URL to download files without authentication. The S3 bucket gets a public-read policy applied. File URLs for public buckets point directly to the S3 endpoint: 
https://bucket.sparkdb.pro/spark-{userId}-{name}-{rand4}/{filename}

​
S3 Bucket Policy

When a bucket is created as public, SparkDB applies this policy to the underlying MinIO bucket: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicRead",
      "Effect": "Allow",
      "Principal": "*",
      "Action": ["s3:GetObject"],
      "Resource": ["arn:aws:s3:::{bucketName}/*"]
    }
  ]
}
This enables direct S3 downloads without authentication, useful for CDN integration and high-traffic assets.

​
When to Use Public

  • Static website assets (CSS, JS, images)
  • Public file distribution
  • CDN-origin storage
  • Open data sets

​
Changing Visibility

​
Via Dashboard

When creating a bucket, check the Public bucket option.

​
Via API

Toggle visibility after creation:
curl
curl -X POST https://api.sparkdb.pro/api/v1/buckets/1/visibility \
  -H "x-api-key: spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"visibility":"public"}'
Valid values: "public" or "private".

​
How It Works

Changing visibility updates both the database record and the underlying MinIO bucket policy. Public visibility applies a public-read S3 policy; private visibility removes it.