> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fileloom.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Supabase Storage Integration

> Store generated PDFs in Supabase Storage, fully integrated with your Supabase project.

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

## Prerequisites

Before connecting Supabase to Fileloom, you need:

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

## Setting Up Supabase Storage

<Steps>
  <Step title="Open Supabase Dashboard">
    Go to your [Supabase project dashboard](https://supabase.com/dashboard).
  </Step>

  <Step title="Enable Storage">
    Navigate to **Storage** in the sidebar.
  </Step>

  <Step title="Create Bucket">
    Click **New bucket** and configure:

    * Name: `fileloom-pdfs` (or your preference)
    * Public: Off (recommended)
  </Step>

  <Step title="Get Credentials">
    Go to **Settings** → **API** to find your project URL and service key.
  </Step>
</Steps>

## 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...
```

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

## Connecting Supabase to Fileloom

<Steps>
  <Step title="Open Workspace Settings">
    Click the settings icon in your workspace sidebar to open **Workspace Settings**.
  </Step>

  <Step title="Go to Integrations">
    Select **Integrations** from the left menu.
  </Step>

  <Step title="Click Connect on Supabase Storage">
    In the Storage Integrations section, find **Supabase Storage** and click the **Connect** button.
  </Step>

  <Step title="Fill Out the Connection Form">
    Enter your Supabase credentials and configuration (see fields below).
  </Step>

  <Step title="Click Connect">
    Click **Connect** to save. Fileloom automatically runs a connection test to verify your credentials and bucket access.
  </Step>

  <Step title="Connection Enabled">
    If the test passes, your Supabase connection is approved and you'll see a **Connected** badge next to Supabase Storage.
  </Step>
</Steps>

### Connection Form Fields

| Field                | Description               | Example                                            |
| -------------------- | ------------------------- | -------------------------------------------------- |
| **Connection Name**  | Friendly name             | Production Supabase                                |
| **Project URL**      | Your Supabase project URL | [https://xyz.supabase.co](https://xyz.supabase.co) |
| **Bucket Name**      | Storage bucket name       | fileloom-pdfs                                      |
| **Service Role Key** | Service role API key      | eyJhbG...                                          |
| **Path Pattern**     | File organization pattern | {year}/{month}/{filename}                          |

## Configure Storage Mode

After connecting Supabase, configure how Fileloom uses it:

1. In the **Settings** section below your connections, find **Save on**
2. 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:

1. Go to **Storage** → **Policies**
2. Click **New Policy** on your bucket
3. Select **For full customization**
4. Add policy:

```sql theme={null}
-- 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

```sql theme={null}
-- 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

<CardGroup cols={2}>
  <Card title="Use Private Buckets" icon="lock">
    Keep buckets private and use signed URLs for access
  </Card>

  <Card title="Organize by Date" icon="folder">
    Use date-based paths for easier management and cleanup
  </Card>

  <Card title="Monitor Storage" icon="chart-pie">
    Set up alerts before hitting storage limits
  </Card>

  <Card title="Backup Keys" icon="key">
    Store service role key securely; regenerating invalidates the old one
  </Card>
</CardGroup>

## Integration with Your App

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

### JavaScript/TypeScript

```javascript theme={null}
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

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

### Delete Files

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