Platform AWS storage setup

For platform operators who do not use AWS every day. Use when provisioning per-tenant storage for File Cabinets and document uploads.

S3 buckets do not have access keys. You create a bucket, then a separate IAM user with an access key allowed to use that bucket only.

What you need at the end

Piece	PilotBPM field
S3 bucket	Bucket name + Region
IAM access key	Access key ID (AKIA…) + Secret access key
Optional KMS	Key ARN or alias (File Cabinets envelope encryption)

---

1. Create the S3 bucket

1. Sign in at AWS Console.
2. Search S3 → open S3 → Create bucket.

Setting	Value
Bucket name	Globally unique, e.g. pilotbpm-acme-files
Region	e.g. us-east-1 — write this down
Block Public Access	All four options ON
Default encryption	Enable (SSE-S3 is fine)

3. Create bucket. You have a name and region — no access key yet.

---

2. Create IAM policy (one bucket only)

1. Search IAM → Policies → Create policy → JSON tab.
2. Paste (replace YOUR-BUCKET-NAME):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
    },
    {
      "Effect": "Allow",
      "Action": ["textract:DetectDocumentText"],
      "Resource": "*"
    }
  ]
}

3. Name it e.g. PilotBPM-Acme-S3 → Create policy. (Omit Textract block if not using OCR.)

Optional KMS — add kms:Encrypt, kms:Decrypt, kms:GenerateDataKey on your CMK ARN.

---

3. Create IAM user and access key

1. IAM → Users → Create user (e.g. pilotbpm-acme-storage).
2. No console access → attach the policy from step 2 → Create user.
3. Open the user → Security credentials → Access keys → Create access key.
4. Choose Application running outside AWS → create.
5. Copy Access key ID and Secret now — the secret is shown only once.

This is what PilotBPM asks for — not something on the S3 bucket page.

---

4. Enter in PilotBPM

Platform → Storage → Manage (tenant) or Bucket pool → Configure S3:

Field	Value
Use S3 backend	ON
Endpoint	Blank for AWS S3
Region	Same as bucket
Bucket name	Exact S3 name
Access key ID / Secret	From step 3

Save → Test connection → Connected.

Same settings appear under tenant Admin → Integrations → Storage.

---

5. Optional: KMS & Textract

On Platform → Storage → Manage for the tenant:

• KMS — enable, paste key ARN, Test KMS.
• Textract — enable, Use storage credentials ON, same region → Save.

---

Troubleshooting

Error	Fix
Access Denied	IAM policy bucket ARN typo or missing ListBucket
Wrong endpoint / region error	Region in PilotBPM must match bucket region
NoSuchBucket	Bucket name typo
InvalidAccessKeyId	Wrong key or deleted — create new key on IAM user
Can't find keys on S3	Keys live on IAM user → Security credentials

---

Checklist

• Bucket created, public access blocked
• IAM policy scoped to one bucket
• IAM user + access key copied
• PilotBPM test = Connected
• (Optional) KMS + Textract

Repository copy: docs/PLATFORM-AWS-STORAGE-SETUP.md