Skip to main content
Humm can sync SaaS data into an S3 bucket in your AWS account instead of storing that synced data in Humm-managed storage. In this setup:
  • The synced data lives in your S3 bucket.
  • Humm still manages the Glue catalog and query path.
  • Humm and Airbyte assume a role in your AWS account to write, validate, and query the synced data.

​
Before You Start

You will need:
  • Permission in your AWS account to create or update an S3 bucket, IAM policy, and IAM role
  • Organization admin access in Humm
  • Three values from Humm:
    • The Airbyte principal ARN
    • The external ID
    • Humm’s AWS account ID
You can get those values from Settings > Data Storage in Humm.

​
1. Create or Choose an S3 Bucket

Create a new bucket or choose an existing one for Humm sync data. Recommendations:
  • Use a dedicated bucket for Humm sync data
  • Keep Block Public Access enabled
  • Choose the AWS region you want Humm to use for sync storage
  • Avoid pointing Humm at a bucket that contains unrelated production data
Important Humm uses the bucket as the root warehouse location. Use a dedicated bucket instead of a shared bucket with unrelated objects. Do not allow any other processes to write to this bucket.

​
2. Create an IAM Permission Policy

Create an IAM policy that gives the Humm sync role access to the bucket. Replace <YOUR_BUCKET_NAME> with your bucket name: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject*",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket*"
      ],
      "Resource": [
        "arn:aws:s3:::<YOUR_BUCKET_NAME>",
        "arn:aws:s3:::<YOUR_BUCKET_NAME>/*"
      ]
    }
  ]
}
Why these permissions are needed:
  • s3:ListBucket* lets Humm discover objects and prefixes
  • s3:PutObject lets Humm write synced data and run connection validation
  • s3:DeleteObject lets Humm clean up connector-owned data and remove the validation file
  • s3:GetObject* lets Humm query synced data

​
3. Create an IAM Role for Humm

Create an IAM role in the same AWS account as the bucket and attach the policy from the previous step. When AWS asks who can assume the role, use a custom trust policy. Replace these placeholders with the values shown in Humm:
  • <AIRBYTE_PRINCIPAL_ARN_FROM_HUMM>
  • <HUMM_AWS_ACCOUNT_ID_FROM_HUMM>
  • <EXTERNAL_ID_FROM_HUMM>
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "<AIRBYTE_PRINCIPAL_ARN_FROM_HUMM>",
          "arn:aws:iam::<HUMM_AWS_ACCOUNT_ID_FROM_HUMM>:root"
        ]
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<EXTERNAL_ID_FROM_HUMM>"
        }
      }
    }
  ]
}
Why there are two trusted principals:
  • Airbyte assumes the role to write sync data into your bucket
  • Humm assumes the role to validate access, query the synced data, and clean up connector-owned objects when needed
After you create the role, copy the Role ARN. You will enter it in Humm.

​
4. Optional: If Your Bucket Uses SSE-KMS

If the bucket uses SSE-KMS with a customer-managed KMS key, the IAM role also needs permission to use that key. At a minimum, allow:
  • kms:Decrypt
  • kms:Encrypt
  • kms:GenerateDataKey
  • kms:DescribeKey
You may also need to update the KMS key policy so the role can use the key. If your organization uses restrictive KMS, SCP, VPC endpoint, or bucket policy controls, contact Humm so we can help verify the final policy set.

​
5. Enter the Settings in Humm

In Humm:
  1. Go to Settings > Data Storage
  2. Select Customer-hosted
  3. Enter your S3 bucket name
  4. Select the bucket region
  5. Paste the IAM role ARN
  6. Click Test connection
  7. Click Save
The test connection verifies that Humm can:
  • Reach the bucket
  • Assume the role
  • Write a temporary validation object
  • Delete that validation object
During validation, Humm writes and deletes a temporary file at .humm/validation.txt.

​
6. Start or Re-run Your Sync

Once the storage settings are saved, create a new Data Sync connector or re-run setup for an existing one. Humm will then:
  • Configure itself to write into your S3 bucket
  • Keep the Glue catalog in Humm-managed AWS
  • Query the synced data through Athena

​
Troubleshooting

If Test connection fails:
  • Confirm the bucket name and region are correct
  • Confirm the IAM role ARN is correct
  • Confirm the trust policy includes both principals
  • Confirm the sts:ExternalId matches the value shown in Humm
  • Confirm the role has the S3 permissions shown above
  • If using SSE-KMS, confirm the role can use the KMS key
  • Check for AWS Organizations SCPs, bucket policies, or VPC endpoint policies that may block access

​
Do I Need a Bucket Policy?

Usually, no. In the standard setup, the IAM role permissions and trust relationship are enough. You only need additional bucket policy changes if your AWS environment uses explicit deny rules or other organization-level controls.

​
Need Help?

If you want, Humm can review your proposed trust policy and role ARN before you save the configuration.