Amazon S3 Connector Guide

The Amazon S3 connector lets Tealfabric workflows store and retrieve files in S3 buckets using AWS Signature Version 4 authentication. This guide covers setup, common object operations, and reliability practices for production-grade file automation.

When to use this connector

Use this connector when workflows need to archive documents, publish generated exports, or retrieve files for downstream processing. It works well for storage-backed automation where object keys and metadata are part of the business process. A clear key naming strategy makes listing, retention, and recovery much easier.

Prerequisites

Before configuring the integration, create an IAM principal with scoped permissions for the bucket and operations you plan to run. Confirm the bucket exists in the expected region and that your credentials can access it. Least-privilege access and region alignment are the most important factors for stable behavior.

Configuration reference

Connector credentials and defaults are stored in integration configuration and reused for runtime requests. Keep secrets secure and rotate them according to policy.

• access_key_id (required): AWS access key ID for the IAM principal.
• secret_access_key (required): AWS secret key paired with the access key.
• region (required): AWS region where the bucket is hosted.
• bucket_name (required): Target S3 bucket name.
• timeout_seconds (optional): Timeout for connector operations.

Upload objects to S3

The send operation is used for object uploads and metadata writes. Keep keys deterministic and set the correct content_type to improve downstream consumption.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type UploadResult = {
  key?: string;
  bucket?: string;
  etag?: string;
  size?: number;
};

async function uploadReport(
  integrationId: string,
  csvBase64: string
): Promise<UploadResult> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "send",
        key: "exports/2026/05/report.csv",
        file_content: csvBase64,
        content_type: "text/csv",
        metadata: {
          source: "processflow",
          environment: "prod",
        },
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as { data?: UploadResult };
  if (!payload.data) throw new Error("Missing S3 upload payload");
  return payload.data;
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "send",
    "key": "exports/2026/05/report.csv",
    "file_content": "<BASE64_FILE_CONTENT>",
    "content_type": "text/csv"
  }'

{
  "success": true,
  "data": {
    "key": "exports/2026/05/report.csv",
    "bucket": "my-bucket",
    "etag": "\"abc123def456\"",
    "size": 128
  }
}

Download and list objects

Use receive with download for single object retrieval and list for prefix-based scanning. Prefix and suffix filters are useful for partitioned data layouts and controlled batch processing.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type ListedObject = {
  key?: string;
  size?: number;
  last_modified?: string;
  etag?: string;
};

async function listDailyExports(integrationId: string): Promise<ListedObject[]> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "receive",
        action: "list",
        prefix: "exports/2026/05/",
        suffix: ".csv",
        max_keys: 100,
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = (await response.json()) as { data?: ListedObject[] };
  if (!payload.data) throw new Error("Missing S3 list payload");
  return payload.data;
}

Validate connectivity and troubleshoot safely

Run test after IAM key rotation, bucket policy updates, or regional changes. Most failures come from invalid credentials, insufficient bucket permissions, or wrong region/bucket mapping. Use execution IDs and HTTP details in logs to accelerate debugging and recovery.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "test"
  }'

{
  "success": true,
  "data": {
    "status": "ok",
    "bucket": "my-bucket",
    "region": "us-east-1"
  }
}

Additional references

For API details and security design, review Amazon S3 documentation, the S3 API reference, and AWS Signature Version 4. Maintaining clear key conventions and access boundaries is essential for long-term reliability.