> For the complete documentation index, see [llms.txt](https://docs.silkline.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.silkline.ai/configuration/custom-s3-storage.md).

# Custom File Storage

Host your organization's Silkline files in your own AWS S3 bucket using cross-account access

## Overview

With custom file storage, the documents and files your organization uploads to Silkline from setup on are stored in an S3 bucket in **your** AWS account, in the commercial AWS region you choose. Master data and metadata stay in Silkline, in the United States.

Silkline never holds long-lived credentials for your account. It assumes an IAM role you create, scoped to your bucket, for credentials that expire after one hour, and only with an ExternalId unique to your organization.

{% hint style="warning" %}
**Commercial AWS regions only.** Your bucket must live in a commercial AWS region (for example `us-east-1` or `eu-central-1`). Buckets in AWS GovCloud or China regions are in separate AWS partitions that Silkline cannot assume roles into.

**Not available to FedRAMP or ITAR organizations.** Silkline stores these organizations' files in its own storage. If custom storage was set up before FedRAMP or ITAR was enabled, files already in your bucket stay there and are not migrated; disable custom storage to store new files with Silkline.
{% endhint %}

{% hint style="info" %}
**You are responsible for malware scanning.** Silkline scans files in its own storage for malware and blocks any it flags. Files in your bucket are outside that scanning, so scan them yourself, for example by enabling [Amazon GuardDuty Malware Protection for S3](https://docs.aws.amazon.com/guardduty/latest/ug/gdu-malware-protection-s3.html) on the bucket.

**Document types are not detected automatically.** Silkline detects the document type of a file, such as a quote or a certificate, only for files in its own storage. Set document types on files in your bucket by hand.
{% endhint %}

## What is stored where

<figure><img src="https://1158234432-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbwxUq49WUtHgRhcDnQkz%2Fuploads%2Fgit-blob-a2fe42b9ecebbb1030a875b5791286ed502bf7f3%2Fcustom-file-storage-data-residency.png?alt=media" alt="Diagram: your people and systems send records to the Silkline application in the United States, which stores master data, file records, extracted data, and accounts; files are read and written in an S3 bucket in your AWS account, secured by your IAM role and encryption key, and each file record points to its file in your bucket by file ID"><figcaption><p>Documents and files uploaded from setup on are stored in your bucket; master data and metadata stay in Silkline</p></figcaption></figure>

| Data                           | Stored in                     | Examples                                                                                                         |
| ------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Documents and files            | Your S3 bucket, from setup on | Part files and CAD models, quotes, purchase order PDFs, email attachments, shipment and supplier documents       |
| Master data                    | Silkline, United States       | Suppliers, parts, orders, quotes, requests, shipments, contacts                                                  |
| File records                   | Silkline, United States       | Filename, file type, uploader, upload date, attached records, and the file ID that names the file in your bucket |
| Extracted data and messages    | Silkline, United States       | Fields read from documents, email subjects and bodies                                                            |
| Accounts, activity, and images | Silkline, United States       | Users and sign-in, audit history, application logs, avatars, supplier logos                                      |

Each file record in Silkline holds the file's ID, and the file itself is stored in your bucket as `<organization ID>/<file ID>` followed by its extension, for example `<organization ID>/<file ID>.pdf`. Silkline reads a file from your bucket only to process it in memory, for example to extract data with AI or render a 3D preview, and does not keep a copy.

Data files that a file-based integration fetches from your systems, such as CSV exports picked up over SFTP, are cached in Silkline storage, not in your bucket.

<figure><img src="https://1158234432-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbwxUq49WUtHgRhcDnQkz%2Fuploads%2Fgit-blob-bb66aac40862d7220500157583a686e8613733cd%2Fcustom-file-storage-part-files.png?alt=media" alt="A part in Silkline: the identification and specification fields are marked as stored in Silkline, and the attached file is marked as stored in your S3 bucket"><figcaption><p>A part's details are stored in Silkline; its attached files are stored in your bucket</p></figcaption></figure>

## How Silkline connects to your bucket

1. Silkline's application signs in to a dedicated Silkline principal, the IAM role `silkline-s3-bridge-production` in Silkline's AWS account, with a short-lived workload token. That principal can assume only roles named `silkline-s3-access-production`.
2. It assumes your role with your organization's ExternalId and receives credentials that expire after one hour. Each session is named for your Silkline organization and appears in your CloudTrail. To also log each file read and write, turn on [CloudTrail data events for S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cloudtrail-logging-s3-info.html) on the bucket.
3. It signs upload and download links with those credentials. Browsers upload and download directly to and from your bucket over HTTPS. The links expire within an hour, and file contents never pass through Silkline's servers.

Silkline needs only `s3:GetObject` and `s3:PutObject` on your bucket. Every upload is conditional (`If-None-Match: *`), so a file is written once and never overwritten. In US and Canada regions, Silkline uses the S3 FIPS endpoints.

## Before you start

You will need:

* An AWS account where you can create an S3 bucket and an IAM role.
* A Silkline representative to configure your organization. Silkline sets up custom file storage; contact your representative to start.

## Step 1: Create the bucket

Create an S3 bucket in a commercial AWS region. Note the **bucket name** and **region**.

Recommended settings:

* **Block Public Access:** on, for all four settings.
* **Object Ownership:** Bucket owner enforced. Silkline's uploads send no ACL.
* **Default encryption:** SSE-S3, or SSE-KMS with a key you own. If you use your own key, note its **KMS key ARN**.
* **Versioning:** on, so you can recover a file deleted by mistake.
* **CloudTrail S3 data events:** on, if you want a record of each file read and write.
* **Bucket policy:** deny requests that don't use TLS (`aws:SecureTransport` is `false`).

Silkline's uploads rely on the bucket's default encryption and send no encryption headers. Don't add a bucket policy that denies uploads without `x-amz-server-side-encryption` headers, and don't restrict access by IP address.

### CORS configuration

File uploads and downloads happen directly between the browser and your bucket, so the bucket needs a CORS rule allowing the Silkline app origin:

```json
[
  {
    "AllowedOrigins": ["https://app.silkline.ai"],
    "AllowedMethods": ["GET", "PUT"],
    "AllowedHeaders": ["*"],
    "MaxAgeSeconds": 3000
  }
]
```

## Step 2: Create the IAM role

Create an IAM role in the same AWS account as the bucket. The role name must begin with:

```
silkline-s3-access-production
```

You may append a suffix, for example `silkline-s3-access-production-east`. Keep the maximum session duration at one hour.

Attach a permissions policy that grants object access on your bucket:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": "arn:aws:s3:::<your-bucket-name>/*"
    }
  ]
}
```

If the bucket is encrypted with a key you own, also grant the role `kms:Decrypt` and `kms:GenerateDataKey` on that key. If the key policy doesn't delegate to IAM, name the role in the key policy as well.

You set the role's trust policy in Step 4, once you have the ExternalId.

## Step 3: Send Silkline your bucket details

Send your Silkline representative:

| Detail      | Value                                                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Bucket name | The bucket from Step 1                                                                                                          |
| Region      | The bucket's AWS region                                                                                                         |
| Role ARN    | The ARN of the role from Step 2                                                                                                 |
| KMS key ARN | Only if the bucket uses a key you own                                                                                           |
| ExternalId  | Optional. A value you choose, at least 16 characters, mixing letters with numbers or symbols. Otherwise Silkline generates one. |

Silkline configures custom storage in **Organization Settings → File Storage**, then sends you over a secure channel:

* the **ExternalId**, which Silkline sees only once, at setup, and
* the **Silkline principal ARN**: `arn:aws:iam::201233842033:role/system/silkline-s3-bridge-production`.

## Step 4: Set the role's trust policy

Set your role's trust policy to allow only the Silkline principal, and only with the ExternalId:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::201233842033:role/system/silkline-s3-bridge-production"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "sts:ExternalId": "<external-id>" }
      }
    }
  ]
}
```

Once the trust policy is in place, new file uploads in Silkline are stored in your bucket.

{% hint style="danger" %}
The ExternalId is shown **only once** and cannot be retrieved later. If it is lost, rotate it from the File Storage settings page and update the trust policy with the new value.
{% endhint %}

## Rotating the ExternalId

Rotate the ExternalId if it was lost, shared more widely than intended, or may have been exposed. In **Organization Settings → File Storage**, use **Rotate** next to the ExternalId; this needs the **Edit Integration** permission. The previous value stops working immediately, and Silkline cannot access your bucket until you update the role's trust policy with the new value, which is shown only once.

## Revoking Silkline's access

To end Silkline's access to your bucket at any time, remove the role's permissions policy or delete the role. Your files stay in your bucket, and Silkline can no longer show or process them.

## Disabling custom storage

In **Organization Settings → File Storage**, use **Disable custom storage**. Disabling reverts your organization to Silkline's default storage. Before confirming, be aware:

* **Files already stored in your bucket are no longer accessible in Silkline.** They remain in your bucket, but nothing is migrated, so previews and downloads of those files stop working.
* New uploads are stored in Silkline's storage going forward.
* The ExternalId is revoked immediately.

## Existing files

Files are not migrated automatically in either direction. Files uploaded before enabling custom storage remain in Silkline's storage, and files uploaded while it was enabled remain in yours. Contact Silkline support if you need existing files migrated.
