From bd1e42e2011edb9937e0f7842f31d2e1e3f390df Mon Sep 17 00:00:00 2001
From: "c1-dev-bot[bot]" <2740113+c1-dev-bot[bot]@users.noreply.github.com>
Date: Fri, 17 Jul 2026 14:13:37 +0000
Subject: [PATCH] docs: add cross-account bucket policy, s3_bucket_region
 field, and fix step reference

- Add cross-account S3 bucket policy section for setups where the bucket
  and IAM role are in different AWS accounts
- Document the optional S3 bucket region field in Step 4
- Fix Step 4 Role ARN reference from "Step 2" to "Step 3"
---
 product/admin/external-datasources.mdx | 59 +++++++++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/product/admin/external-datasources.mdx b/product/admin/external-datasources.mdx
index 0b6ae677..4fdd319b 100644
--- a/product/admin/external-datasources.mdx
+++ b/product/admin/external-datasources.mdx
@@ -157,6 +157,60 @@ Copy and save the **Role ARN** for the newly created policy. The Role ARN is for
 </Step>
 </Steps>
 
+### Cross-account S3 buckets
+
+<Tip>
+This section is only required when the S3 bucket is in a **different AWS account** than the IAM role you created in Step 2. If the bucket and role are in the same account, skip to Step 4.
+</Tip>
+
+When the S3 bucket lives in a different AWS account than the C1Integration role, the identity policy on the role (Step 3) is not sufficient on its own. The bucket's account must also grant access to the role via a **bucket policy**.
+
+<Steps>
+<Step>
+Sign into the AWS account that **owns the S3 bucket**.
+</Step>
+<Step>
+Navigate to the **S3** console and open the target bucket.
+</Step>
+<Step>
+Click the **Permissions** tab, then under **Bucket policy** click **Edit**.
+</Step>
+<Step>
+Add the following policy, replacing `<ROLE_ACCOUNT_ID>` with the AWS account ID where you created the C1Integration role and `<BUCKET_NAME>` with the name of your bucket:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": "arn:aws:iam::<ROLE_ACCOUNT_ID>:role/C1Integration"
+      },
+      "Action": [
+        "s3:GetObject",
+        "s3:GetObjectAttributes",
+        "s3:ListBucket",
+        "s3:GetBucketLocation"
+      ],
+      "Resource": [
+        "arn:aws:s3:::<BUCKET_NAME>",
+        "arn:aws:s3:::<BUCKET_NAME>/*"
+      ]
+    }
+  ]
+}
+```
+
+<Tip>
+If you also plan to **write** to this bucket (for example, to push audit logs), add `"s3:PutObject"` to the `Action` list.
+</Tip>
+</Step>
+<Step>
+Click **Save changes**.
+</Step>
+</Steps>
+
 ### Step 4: Configure the external data source in C1
 
 <Steps>
@@ -164,12 +218,15 @@ Copy and save the **Role ARN** for the newly created policy. The Role ARN is for
 Return to the C1 **Integrations** > **External data sources** page if necessary and navigate to your newly created external data source.
 </Step>
 <Step>
-Paste the Role ARN you generated in Step 2 into the **Role ARN** field.
+Paste the Role ARN you copied in Step 3 into the **Role ARN** field.
 </Step>
 <Step>
 Enter the name of the S3 bucket that contains the files you want to use in C1 in the **S3 bucket** field.
 </Step>
 <Step>
+**Optional.** Enter the AWS region of the S3 bucket in the **S3 bucket region** field (for example, `us-east-1`). If left blank, C1 auto-detects the bucket's region.
+</Step>
+<Step>
 Click **Save**.
 </Step>
 </Steps>