Connect AWS for Storage Audit

BlobRouter v0.1 · Last updated: August 2026 · Architecture version: 2.0

This is the most important setup guide. Follow it carefully — most connection failures are External ID or trust-policy mismatches.

Overview

You are creating a read-only IAM role in your AWS account that BlobRouter can assume temporarily (STS) to list buckets and object metadata. With this role BlobRouter cannot modify, delete, or upload objects. Temporary credentials expire in about one hour and are never stored. You will need values from the BlobRouter dashboard (Connect AWS):

BlobRouter’s AWS account ID (12 digits)
Your unique External ID

Step 1: Create the IAM role

Open the AWS IAM console → Roles
Choose Create role
Trusted entity type: AWS account
Select Another AWS account
Account ID: paste BlobRouter’s account ID from the dashboard (do not invent a placeholder)
Check Require external ID
External ID: paste the value shown in the BlobRouter dashboard (copy/paste — do not retype)
Leave MFA options as-is unless your org requires MFA on assume-role
Choose Next

Your trust policy should look like this (IDs come from the dashboard):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::BLOBROUTER_ACCOUNT_ID:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID_FROM_DASHBOARD"
        }
      }
    }
  ]
}

The dashboard generates this JSON with your real values — prefer copying from there.

Step 2: Attach permissions policy

On the permissions step, choose Create policy (JSON) and paste this exact policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BlobRouterScannerReadOnly",
      "Effect": "Allow",
      "Action": [
        "s3:ListAllMyBuckets",
        "s3:ListBucket",
        "s3:GetBucketLocation",
        "s3:GetMetricsConfiguration",
        "s3:GetObject",
        "s3:GetObjectAttributes",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:ListMetrics"
      ],
      "Resource": "*"
    }
  ]
}

Do not use s3:HeadObject or s3:GetBucketMetricsConfiguration. Those action names are invalid in IAM. The HeadObject API is authorized by s3:GetObject. Metrics configuration uses s3:GetMetricsConfiguration.

Name the policy something like BlobRouterScannerReadOnly, create it, attach it to the role, then continue.

Step 3: Name and create the role

Role name: BlobRouterScanner (or any name you prefer)
Optional description: Read-only S3 audit for BlobRouter
Choose Create role

Step 4: Copy the Role ARN

Open the role you just created
Copy the ARN from the summary

Format:

arn:aws:iam::123456789012:role/BlobRouterScanner

Step 5: Paste into BlobRouter

Open Dashboard → Connect AWS
Paste the Role ARN
Choose Connect AWS Account

BlobRouter will AssumeRole, verify ListBuckets, store the connection, and start your first scan.

Troubleshooting

Error: Could not assume the IAM role / `connection_failed`

External ID must match exactly (copy from dashboard)
Trust policy Account ID must be BlobRouter’s 12-digit account ID from the dashboard
Role must include the permissions policy above
Wait ~10 seconds after creating the role (IAM propagation)

Error: Invalid Role ARN format / `invalid_role_arn`

Must start with arn:aws:iam::
Account ID must be exactly 12 digits
Must include /role/RoleName after the account ID

Error: Scanner configuration error / `scanner_credentials_missing`

This is a BlobRouter-side configuration issue, not a problem with your IAM role. Contact support.

AWS IAM Console: `Invalid Action: s3:HeadObject does not exist`

Use s3:GetObject instead. The HeadObject API uses the GetObject IAM action.

AWS IAM Console: `s3:GetBucketMetricsConfiguration does not exist`

Use s3:GetMetricsConfiguration instead.

Role connects but scan finds little waste

Access metrics improve classification. Without CloudWatch / metrics access, BlobRouter falls back to LastModified as a proxy for hot/cold/archive. That is expected and still useful.

Security notes

Role has no write, delete, or PutObject permissions
BlobRouter uses STS temporary credentials only for scans
Revoke access anytime by deleting the role or removing the trust statement

Next: review results in the dashboard, then optionally approve migrations or install the SDK.

Getting Started

Guides

Examples

SDK Reference

API

Concepts

Billing

Product

Connect AWS for Storage Audit

Overview

Step 1: Create the IAM role

Step 2: Attach permissions policy

Step 3: Name and create the role

Step 4: Copy the Role ARN

Step 5: Paste into BlobRouter

Troubleshooting

Error: Could not assume the IAM role / `connection_failed`

Error: Invalid Role ARN format / `invalid_role_arn`

Error: Scanner configuration error / `scanner_credentials_missing`

AWS IAM Console: `Invalid Action: s3:HeadObject does not exist`

AWS IAM Console: `s3:GetBucketMetricsConfiguration does not exist`

Role connects but scan finds little waste

Security notes

​Overview

​Step 1: Create the IAM role

​Step 2: Attach permissions policy

​Step 3: Name and create the role

​Step 4: Copy the Role ARN

​Step 5: Paste into BlobRouter

​Troubleshooting

​Error: Could not assume the IAM role / connection_failed

​Error: Invalid Role ARN format / invalid_role_arn

​Error: Scanner configuration error / scanner_credentials_missing

​AWS IAM Console: Invalid Action: s3:HeadObject does not exist

​AWS IAM Console: s3:GetBucketMetricsConfiguration does not exist

​Role connects but scan finds little waste

​Security notes

Overview

Step 1: Create the IAM role

Step 2: Attach permissions policy

Step 3: Name and create the role

Step 4: Copy the Role ARN

Step 5: Paste into BlobRouter

Troubleshooting

Error: Could not assume the IAM role / `connection_failed`

Error: Invalid Role ARN format / `invalid_role_arn`

Error: Scanner configuration error / `scanner_credentials_missing`

AWS IAM Console: `Invalid Action: s3:HeadObject does not exist`

AWS IAM Console: `s3:GetBucketMetricsConfiguration does not exist`

Role connects but scan finds little waste

Security notes