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

# Overview

> Connect Fileloom to external storage providers like AWS S3 and Supabase to store generated PDFs in your own infrastructure.

Fileloom integrates with external storage providers, giving you flexibility in where your generated PDFs are stored.

## Why External Storage?

By default, Fileloom stores generated PDFs in Firebase Storage with permanent public URLs. External storage lets you:

* **Keep PDFs in your infrastructure** — Meet compliance and data residency requirements
* **Integrate with existing workflows** — Use your current storage systems
* **Control access** — Manage permissions with your own policies
* **Reduce costs** — Leverage existing storage allocations

## Supported Providers

<CardGroup cols={2}>
  <Card title="AWS S3" icon="aws" href="/integrations/aws-s3">
    Store PDFs in Amazon S3 buckets with full control over regions, paths, and permissions
  </Card>

  <Card title="Supabase Storage" icon="database" href="/integrations/supabase">
    S3-compatible storage integrated with your Supabase project
  </Card>
</CardGroup>

## Setting Up Storage Integrations

<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. You'll see the **Storage Integrations** section with all supported providers.
  </Step>

  <Step title="Connect a Provider">
    Find the storage provider you want to use (Amazon S3 or Supabase Storage) and click the **Connect** button.
  </Step>

  <Step title="Enter Credentials">
    Fill out the connection form with your provider credentials (bucket name, access keys, region, etc.).
  </Step>

  <Step title="Automatic Connection Test">
    Click **Connect** to save. Fileloom automatically runs a connection test to verify your credentials and permissions.
  </Step>

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

## Storage Mode Settings

Once you have at least one connection, you can configure how Fileloom handles PDF storage. In the **Settings** section below your connections, choose your preferred **Save on** mode:

| Mode         | Fileloom Storage | External Storage | Best For                            |
| ------------ | ---------------- | ---------------- | ----------------------------------- |
| **Fileloom** | ✅                | ❌                | Simple setup, getting started       |
| **External** | ❌                | ✅                | Compliance, existing infrastructure |
| **Both**     | ✅                | ✅                | Redundancy, migration period        |

### Mode Behaviors

**Fileloom Mode (Default)**

* PDFs stored in Firebase Storage
* Permanent public URLs
* 24-hour signed URLs for secure access
* No external configuration needed

**External Mode**

* PDFs stored only in your connected external provider
* URLs from your storage provider
* If external upload fails, falls back to Fileloom to prevent data loss

**Both Mode**

* PDFs stored in Fileloom AND external provider
* Primary URL from Fileloom
* External copies listed in API response
* Best for gradual migration or backup

## Managing Connections

After connecting a provider, you can manage it from the Integrations page:

* **Primary** — If you have multiple connections, one is marked as Primary and used first
* **Connected / Inactive** — Shows the current status of each connection
* **Actions menu (⋮)** — Edit credentials, run connection test, or disconnect

### Connection Status

| Status        | Description                                |
| ------------- | ------------------------------------------ |
| **Connected** | Working normally, ready to receive files   |
| **Inactive**  | Connection disabled or credentials invalid |

## Path Patterns

Customize how files are organized in your external storage using path pattern variables:

| Variable      | Description           | Example         |
| ------------- | --------------------- | --------------- |
| `{year}`      | Current year          | 2024            |
| `{month}`     | Current month (01-12) | 12              |
| `{day}`       | Current day (01-31)   | 15              |
| `{workspace}` | Workspace ID          | ws\_abc123      |
| `{template}`  | Template ID           | tpl\_xyz789     |
| `{filename}`  | Generated filename    | invoice-001.pdf |
| `{fileid}`    | Unique file ID        | file\_abc123    |

**Example Patterns:**

```
pdfs/{year}/{month}/{filename}
→ pdfs/2024/12/invoice-001.pdf

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

invoices/{template}/{fileid}.pdf
→ invoices/tpl_invoice_v2/file_abc123.pdf
```

## API Response

When external storage is configured, the API response includes external copy information:

```json Response theme={null}
{
  "success": true,
  "data": {
    "fileId": "file_abc123",
    "url": "https://storage.googleapis.com/...",
    "storageProvider": "firebase",
    "externalCopies": [
      {
        "provider": "s3",
        "name": "Production S3",
        "url": "https://my-bucket.s3.amazonaws.com/pdfs/2024/12/invoice.pdf",
        "expiresAt": "2024-12-16T10:30:00Z"
      }
    ]
  }
}
```

## Plan Availability

External storage integrations are available on all plans.

| Feature              | Free | Starter | Growth | Scale+ |
| -------------------- | ---- | ------- | ------ | ------ |
| External Storage     | ✅    | ✅       | ✅      | ✅      |
| Multiple Connections | ❌    | ❌       | ✅      | ✅      |

## Next Steps

<CardGroup cols={2}>
  <Card title="AWS S3 Setup" icon="aws" href="/integrations/aws-s3">
    Step-by-step guide for Amazon S3
  </Card>

  <Card title="Supabase Setup" icon="database" href="/integrations/supabase">
    Step-by-step guide for Supabase Storage
  </Card>
</CardGroup>