Supabase Storage Integration

Connect Fileloom to Supabase Storage to keep generated PDFs alongside your application data.

Prerequisites

Before connecting Supabase to Fileloom, you need:

A Supabase project
Storage enabled on your project
A storage bucket created
Service role key (for server-side access)

Setting Up Supabase Storage

Open Supabase Dashboard

Go to your Supabase project dashboard.

Enable Storage

Navigate to Storage in the sidebar.

Create Bucket

Click New bucket and configure:

Name: fileloom-pdfs (or your preference)
Public: Off (recommended)

Get Credentials

Go to Settings → API to find your project URL and service key.

Getting Your Credentials

Project URL

Found in Settings → API → Project URL:

https://xyzabcdef.supabase.co

Service Role Key

Found in Settings → API → Service role key (secret):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The service role key bypasses Row Level Security. Keep it secret and never expose it in client-side code.

Connecting Supabase to Fileloom

Open Workspace Settings

Click the settings icon in your workspace sidebar to open Workspace Settings.

Go to Integrations

Select Integrations from the left menu.

Click Connect on Supabase Storage

In the Storage Integrations section, find Supabase Storage and click the Connect button.

Fill Out the Connection Form

Enter your Supabase credentials and configuration (see fields below).

Click Connect

Click Connect to save. Fileloom automatically runs a connection test to verify your credentials and bucket access.

Connection Enabled

If the test passes, your Supabase connection is approved and you’ll see a Connected badge next to Supabase Storage.

Connection Form Fields

Field	Description	Example
Connection Name	Friendly name	Production Supabase
Project URL	Your Supabase project URL	https://xyz.supabase.co
Bucket Name	Storage bucket name	fileloom-pdfs
Service Role Key	Service role API key	eyJhbG…
Path Pattern	File organization pattern	//

Configure Storage Mode

After connecting Supabase, configure how Fileloom uses it:

In the Settings section below your connections, find Save on
Choose your preferred mode:

Mode	Behavior
Fileloom	PDFs saved to Fileloom only (Supabase connection inactive)
External	PDFs saved to Supabase only
Both	PDFs saved to both Fileloom and Supabase

Path Pattern Examples

Organize files in your bucket:

# By date
{year}/{month}/{filename}
→ 2024/12/invoice-001.pdf

# By workspace and date
{workspace}/{year}-{month}-{day}/{filename}
→ ws_abc123/2024-12-15/invoice-001.pdf

# Flat with unique IDs
{fileid}.pdf
→ file_abc123xyz.pdf

URL Format

Files are accessible via Supabase Storage URLs: Private bucket (signed URL):

https://xyz.supabase.co/storage/v1/object/sign/fileloom-pdfs/2024/12/invoice.pdf?token=...

Public bucket:

https://xyz.supabase.co/storage/v1/object/public/fileloom-pdfs/2024/12/invoice.pdf

Bucket Policies

Private Bucket (Recommended)

For private access, no additional policies needed. Files accessed via signed URLs.

Public Bucket

If you need public access, create the bucket as public or add a policy:

Go to Storage → Policies
Click New Policy on your bucket
Select For full customization
Add policy:

-- Allow public read access
CREATE POLICY "Public read access"
ON storage.objects FOR SELECT
USING (bucket_id = 'fileloom-pdfs');

Row Level Security

Supabase Storage supports RLS for fine-grained access control.

Example: User-specific folders

-- Allow users to read their own files
CREATE POLICY "Users can read own files"
ON storage.objects FOR SELECT
USING (
  bucket_id = 'fileloom-pdfs' 
  AND (storage.foldername(name))[1] = auth.uid()::text
);

For Fileloom integration, the service role key bypasses RLS, so files are always uploaded successfully.

Managing Your Connection

After connecting, you can manage your Supabase integration from the Integrations page:

Primary badge — If you have multiple storage connections, the primary one is used first
Connected / Inactive — Shows current connection status
Actions menu (⋮) — Edit credentials, run a new connection test, or disconnect

Troubleshooting

Connection Failed

Symptoms: Connection test fails Solutions:

Verify project URL is correct (no trailing slash)
Check service role key is the full key, not truncated
Ensure bucket exists with exact name
Verify project is not paused

Upload Failed

Symptoms: PDFs not appearing in bucket Solutions:

Check bucket name matches exactly (case-sensitive)
Verify service role key has not been regenerated
Check Supabase project is on a plan with sufficient storage
Review path pattern for invalid characters

Access Denied

Symptoms: 403 errors when accessing files Solutions:

For private buckets, ensure you’re using signed URLs
For public buckets, verify bucket is set to public
Check RLS policies aren’t blocking access

File Not Found

Symptoms: 404 errors for uploaded files Solutions:

Verify path pattern doesn’t create deeply nested folders
Check for special characters in filename
Ensure file wasn’t deleted by Supabase lifecycle rules

Storage Limits

Supabase storage limits by plan:

Plan	Storage	Bandwidth
Free	1 GB	2 GB/month
Pro	100 GB	200 GB/month
Team	100 GB	200 GB/month
Enterprise	Custom	Custom

Best Practices

Use Private Buckets

Keep buckets private and use signed URLs for access

Organize by Date

Use date-based paths for easier management and cleanup

Monitor Storage

Set up alerts before hitting storage limits

Backup Keys

Store service role key securely; regenerating invalidates the old one

Integration with Your App

Since files are in your Supabase project, you can access them directly:

JavaScript/TypeScript

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY)

// Get signed URL for private file
const { data, error } = await supabase.storage
  .from('fileloom-pdfs')
  .createSignedUrl('2024/12/invoice-001.pdf', 3600) // 1 hour expiry

console.log(data.signedUrl)

// Download file
const { data: fileData, error: downloadError } = await supabase.storage
  .from('fileloom-pdfs')
  .download('2024/12/invoice-001.pdf')

List Files

const { data, error } = await supabase.storage
  .from('fileloom-pdfs')
  .list('2024/12', {
    limit: 100,
    offset: 0,
    sortBy: { column: 'created_at', order: 'desc' }
  })

Delete Files

const { error } = await supabase.storage
  .from('fileloom-pdfs')
  .remove(['2024/12/invoice-001.pdf'])

​Prerequisites

​Setting Up Supabase Storage

​Getting Your Credentials

​Project URL

​Service Role Key

​Connecting Supabase to Fileloom

​Connection Form Fields

​Configure Storage Mode

​Path Pattern Examples

​URL Format

​Bucket Policies

​Private Bucket (Recommended)

​Public Bucket

​Row Level Security

​Example: User-specific folders

​Managing Your Connection

​Troubleshooting

​Connection Failed

​Upload Failed

​Access Denied

​File Not Found

​Storage Limits

​Best Practices

Use Private Buckets

Organize by Date

Monitor Storage

Backup Keys

​Integration with Your App

​JavaScript/TypeScript

​List Files

​Delete Files

Prerequisites

Setting Up Supabase Storage

Getting Your Credentials

Project URL

Service Role Key

Connecting Supabase to Fileloom

Connection Form Fields

Configure Storage Mode

Path Pattern Examples

URL Format

Bucket Policies

Private Bucket (Recommended)

Public Bucket

Row Level Security

Example: User-specific folders

Managing Your Connection

Troubleshooting

Connection Failed

Upload Failed

Access Denied

File Not Found

Storage Limits

Best Practices

Integration with Your App

JavaScript/TypeScript

List Files

Delete Files