How to Integrate Retool with AWS S3

Before configuring Retool, set up proper AWS IAM permissions. In the AWS Console, navigate to IAM → Users → Create User. Create a dedicated user for Retool (e.g., retool-s3-integration) rather than using personal credentials. This makes it easy to rotate credentials and apply minimal permissions. Attach an inline or managed policy to this user. The minimum policy for a read/write Retool integration requires s3:ListAllMyBuckets (to list buckets), s3:ListBucket (to list objects in a specific bucket), s3:GetObject, s3:PutObject, and optionally s3:DeleteObject if you want delete capability. Restrict the policy to specific buckets using the Resource field rather than granting access to all buckets. After creating the user, navigate to the user's Security Credentials tab and create an Access Key. Select 'Application running outside AWS' as the use case. Copy the Access Key ID and Secret Access Key — the secret is only shown once. For production environments with self-hosted Retool running on EC2 or ECS: instead of access keys, use IAM Role assumption. Attach an IAM role to your Retool instance with the appropriate S3 permissions. In the Retool resource configuration, select 'Use Instance Role' instead of providing access keys. This is more secure because credentials rotate automatically and are never stored as configuration values.

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Action": [
7        "s3:ListAllMyBuckets"
8      ],
9      "Resource": "arn:aws:s3:::*"
10    },
11    {
12      "Effect": "Allow",
13      "Action": [
14        "s3:ListBucket",
15        "s3:GetBucketLocation"
16      ],
17      "Resource": "arn:aws:s3:::your-bucket-name"
18    },
19    {
20      "Effect": "Allow",
21      "Action": [
22        "s3:GetObject",
23        "s3:PutObject",
24        "s3:DeleteObject"
25      ],
26      "Resource": "arn:aws:s3:::your-bucket-name/*"
27    }
28  ]
29}

In your Retool instance, navigate to the Resources tab in the left sidebar. Click Add Resource. In the resource type selector, find 'Amazon S3' under the Storage & Files category, or search for 'S3'. In the resource configuration panel, enter a descriptive name such as 'AWS S3 Production' or 'Media Assets Bucket'. In the Authentication section, select 'AWS Access Key' and enter your IAM user's Access Key ID and Secret Access Key. Specify the AWS region where your bucket resides (e.g., us-east-1, eu-west-1). This must match the bucket's region. If you have buckets in multiple regions, create separate Retool S3 resources for each region. Optionally, specify a default bucket name. If you do this, queries using this resource will default to that bucket. Leave it blank if you want to specify the bucket dynamically in each query. Click Save Changes. Retool will test the connection by attempting to list your S3 buckets. If successful, a green 'Connection successful' message appears. For Retool Cloud deployments: your S3 bucket must be accessible from Retool's IP ranges (35.90.103.132/30 and 44.208.168.68/30 for us-west-2). If your bucket has a bucket policy that restricts access by IP, add these ranges. Alternatively, if your bucket is public-read, no IP restrictions apply. For maximum security with Retool Cloud, use IAM Role assumption with a cross-account trust policy pointing to Retool's AWS account.

Open a Retool app and create a new query. Select your AWS S3 resource. The S3 query editor shows an Action dropdown with the available S3 operations: List Buckets, List Objects in Bucket, Get Object, Get Presigned URL, Upload File, Delete File, and Copy File. Create a query named listBuckets with action List Buckets. Run it to verify the connection returns your bucket list. This is a useful diagnostic query — if it works, your IAM credentials are valid. Create a second query named listObjects with action List Objects in Bucket. Set Bucket to your target bucket name (either hardcoded or via a component reference like {{ bucketSelect.value }}). Set the Prefix parameter to filter objects by path prefix — for example, documents/ to list only the documents folder, or {{ prefixInput.value }} to make it dynamic. The S3 List Objects action returns an array of objects with Key (full path), Size (bytes), LastModified (ISO timestamp), and ETag fields. Bind the results to a Table component by setting the Table's data property to {{ listObjects.data }}. Add a JavaScript transformer to the listObjects query to format the file size and date for display. Go to the query's Advanced tab → Add Transformer. The transformer receives the raw S3 response in the data variable.

1// listObjects transformer — format S3 object list for display
2const objects = data || [];
3
4return objects.map(obj => ({
5  filename: obj.Key.split('/').pop() || obj.Key,
6  path: obj.Key,
7  size: obj.Size < 1024
8    ? `${obj.Size} B`
9    : obj.Size < 1048576
10    ? `${(obj.Size / 1024).toFixed(1)} KB`
11    : `${(obj.Size / 1048576).toFixed(2)} MB`,
12  lastModified: new Date(obj.LastModified).toLocaleDateString('en-US', {
13    year: 'numeric', month: 'short', day: 'numeric'
14  }),
15  rawSize: obj.Size,
16  rawKey: obj.Key
17})).sort((a, b) => new Date(b.lastModified) - new Date(a.lastModified));

Retool includes a dedicated S3 Uploader component that provides drag-and-drop file upload functionality directly to your S3 bucket — no backend code required. This is the primary differentiator of the native S3 connector versus a generic REST API integration. In the Component panel on the right side of the Retool editor, search for 'S3 Uploader' and drag it onto your canvas. With the component selected, configure it in the right-hand properties panel. Set the S3 resource to your configured AWS S3 resource. Set the Bucket to your target bucket (either hardcoded or dynamic: {{ bucketSelect.value }}). Set the Key Prefix to define where uploads are stored — for example, uploads/{{ currentUser.email }}/ to organize files by uploader. If the key prefix contains the full desired filename, the component uses it directly; otherwise it appends the original filename. Configure the component's Allowed File Types to restrict what can be uploaded (e.g., .pdf,.png,.csv). Set Max File Size in MB to prevent oversized uploads. The S3 Uploader has a built-in event handler: On Upload Success. Wire this to trigger your listObjects query to refresh the file table after each upload, and optionally show a success notification using Retool's built-in notification system. For programmatic uploads (uploading files that come from other Retool components, not user drag-and-drop): use the Upload File action type in a standard S3 query. Reference a FilePicker component's value: set the File Body to {{ filePicker1.value[0] }} to upload the selected file. This approach gives you more control over the upload process, including custom metadata and content-type headers.

1// Programmatic upload using Upload File action type
2// S3 Query: uploadDocument
3// Action: Upload File
4// Configuration:
5{
6  "bucket": "your-bucket-name",
7  "key": "{{ `documents/${currentUser.email}/${moment().format('YYYY-MM-DD')}/${filePicker1.value[0].name}` }}",
8  "fileBody": "{{ filePicker1.value[0] }}",
9  "contentType": "{{ filePicker1.value[0].type }}",
10  "acl": "private"
11}

Presigned URLs allow users to download private S3 objects without requiring AWS credentials — the URL itself carries time-limited authorization. This is the correct pattern for internal tools: objects remain private in S3, but authorized users can download them via a secure, temporary URL. Create a query named getPresignedUrl with action 'Get Presigned URL'. Set the Bucket and Key parameters — the Key should reference the selected row in your file table: {{ table1.selectedRow.data.rawKey }}. Set the Expiration Time in seconds (3600 = 1 hour, 86400 = 24 hours). In your file Table component, add an Action Column with a 'Download' button. Set the button's onClick to trigger the getPresignedUrl query. In the query's On Success event handler, add a handler to open the URL in a new tab: use the built-in 'Open URL' action with the URL set to {{ getPresignedUrl.data }}. For a better UX, you can also display the presigned URL in a Text component or copy it to clipboard using Retool's built-in clipboard utilities. For object metadata: Retool's S3 connector doesn't directly expose a Head Object action for fetching metadata without downloading the file. If you need metadata (content type, custom metadata tags), use the Get Object action with a range request, or store metadata in a separate database table when files are uploaded. For managing large numbers of files across multiple buckets: consider building a metadata layer — a PostgreSQL or Retool Database table that records the S3 key, uploader, upload timestamp, and any business-specific tags when files are uploaded. This enables rich querying and filtering that S3's own API doesn't support efficiently.

1// getPresignedUrl query configuration
2// Action: Get Presigned URL
3// Bucket: your-bucket-name  
4// Key: {{ table1.selectedRow.data.rawKey }}
5// Expiration: 3600
6
7// On Success event handler (JavaScript):
8const url = getPresignedUrl.data;
9window.open(url, '_blank');
10
11// Transformer to format the presigned URL response (if needed):
12// return { downloadUrl: data, expiresAt: new Date(Date.now() + 3600000).toISOString() };