AWS S3 ExecModule

Overview

AwsS3Module connects ValkyrAI workflows to Amazon Simple Storage Service through the bundled AWS SDK v2 client. It covers the high-value bucket and object behaviors represented by n8n's built-in AWS S3 node while following ValkyrAI's native map I/O ABI, IntegrationAccount security, annotation-backed discovery, bounded payloads, and explicit destructive-action controls.

The connector implements nine operations:

• buckets: list_buckets, head_bucket, create_bucket, delete_bucket
• objects: list_objects, head_object, get_object, put_object, delete_object

AWS credentials, service routing, retry boundaries, and response limits cannot be overridden through mapped workflow input. The module contacts only the AWS S3 endpoint selected by the validated AWS region.

Usage

1. Create a dedicated AWS IAM principal for the exact buckets and operations the workflow needs.
2. Store its access key ID and secret access key in an AWS IntegrationAccount, verify the account, and keep it in READY status.
3. Add AwsS3Module to a workflow and bind the account through ExecModuleConfig.authConfig.integrationAccount.
4. Set operation, region, and the operation-specific bucket, key, or content fields.
5. Preserve returned AWS request IDs and immutable object identifiers when reconciling ambiguous provider outcomes.

Do not put AWS credentials in workflow input, module parameters, logs, examples, or object metadata. Raw credential-like inputs are rejected before provider access.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the nine documented operations.
region	string	Every execution	None	AWS region syntax such as us-west-2.
bucket	string	Every operation except list_buckets	None	DNS-compatible S3 bucket name, 3–63 characters; IPv4-shaped names are rejected.
key	string	Object operations except list_objects	None	Non-empty object key, at most 1,024 characters, without a leading or trailing slash.
prefix	string	Optional list_objects filter	None	Up to 1,024 characters.
continuationToken	string	Optional list_objects resume point	None	Opaque provider token, at most 4,096 characters.
limit	integer	List operations	100	1–10,000 returned items. Each S3 page remains at most 1,000 objects.
returnAll	boolean	list_objects	false	Follows provider pages until exhaustion or limit.
contentText	string	put_object, unless base64 is used	None	UTF-8 content; mutually exclusive with contentBase64.
contentBase64	string	put_object, unless text is used	None	Valid base64; mutually exclusive with contentText.
contentType	string	Optional put_object media type	None	Single-line value, at most 255 characters.
metadata	object	Optional put_object metadata	{}	Up to 25 lowercase portable names and single-line values; secret-like names are rejected.
maxDownloadBytes	integer	get_object	1048576	1 byte through 5 MiB. A metadata read checks the declared length before download.
confirmOverwrite	boolean	Intentional replacement by put_object	false	When false, the request uses S3 create-only If-None-Match: * semantics.
confirmDelete	boolean	delete_bucket, delete_object	false	Must be true because deletion can permanently remove data.

Outputs

Every execution returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls, including safe-read retries and pages.
data	object	Single-resource or mutation success	Normalized bucket/object metadata or a stable mutation receipt.
items	array	List success	Bounded buckets or objects.
count	integer	List success	Number of returned items.
hasMore	boolean	List success	Whether another provider page exists.
nextContinuationToken	string	Another object page exists	Opaque ListObjectsV2 continuation for a later execution.
contentBase64	string	get_object success	Bounded downloaded bytes encoded as base64.
contentBytes	integer	get_object or put_object success	Downloaded or uploaded byte count.
requestId	string	AWS supplies one	Bounded request reference for provider support and reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

AWS access keys, secret keys, provider exception text, and unbounded response bodies are never returned.

IntegrationAccount Requirements

Bind exactly one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / S3
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Use the least-privilege IAM actions required by selected operations. Typical mappings are:

• s3:ListAllMyBuckets for list_buckets
• s3:ListBucket and s3:GetBucketLocation for bucket and object listing/read preparation
• s3:CreateBucket for create_bucket
• s3:DeleteBucket for delete_bucket
• s3:GetObject for head_object and get_object
• s3:PutObject for put_object
• s3:DeleteObject for delete_object

Restrict resources to approved buckets and prefixes wherever AWS policy semantics allow it. The current module supports a long-lived access-key pair. Temporary session credentials, role assumption, custom endpoints, and caller-supplied credentials are intentionally deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, region, and resource fields belong in module parameters or mapped input; retry limits use the normalized retry policy.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-s3-release-artifacts"
  },
  "retryPolicy": {
    "maxAttempts": 3
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"list_objects\",\"region\":\"us-west-2\",\"bucket\":\"company-release-artifacts\",\"prefix\":\"releases/\",\"limit\":100}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_buckets	Lists and alphabetizes visible buckets, then applies limit.	Read-only; transient failures are retried.
head_bucket	Verifies that a bucket exists and is accessible.	Read-only; transient failures are retried.
create_bucket	Creates one bucket in the validated region.	External write; one provider attempt.
delete_bucket	Deletes one empty bucket.	Destructive; requires confirmDelete=true; one provider attempt.
list_objects	Uses ListObjectsV2 with optional prefix and opaque continuation.	Read-only; each page can retry independently; bounded at 10,000 results.
head_object	Reads object metadata without downloading the body.	Read-only; transient failures are retried.
get_object	Reads metadata, enforces maxDownloadBytes, then downloads and base64-encodes the object.	Read-only; metadata and body calls can retry independently.
put_object	Uploads bounded UTF-8 or base64 bytes with optional content type and metadata.	External write; one provider attempt; create-only unless overwrite is confirmed.
delete_object	Deletes one object key.	Destructive; requires confirmDelete=true; one provider attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/invalid region, bucket, key, payload, metadata, limit, or confirmation.	No	Correct the named input; no unsafe request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_S3_HTTP_400	Invalid AWS request or bucket-region mismatch.	No	Verify region, bucket, key, and payload.
AWS_S3_HTTP_403	IAM or bucket policy denies access.	No	Grant only the missing action/resource permission.
AWS_S3_HTTP_404	Bucket or object is absent or invisible.	No	Verify the immutable bucket/key.
AWS_S3_HTTP_409	Bucket conflict, non-empty delete, or create collision.	No	Read current provider state and reconcile.
AWS_S3_HTTP_412	Create-only upload found an existing key.	No	Choose a new key or deliberately set confirmOverwrite=true.
AWS_S3_HTTP_429 / 503	S3 throttling or transient service pressure.	Yes for reads	Honor retry guidance; writes remain single-attempt and require reconciliation.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Yes for reads	Verify connectivity and retry a safe read. Reconcile writes before replay.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic write retry	Preserve the request ID and reconcile provider state.

Provider error text is not copied into output, preventing credential echoes and unbounded error payloads.

Example

Upload a create-only JSON release manifest:

{
  "operation": "put_object",
  "region": "us-west-2",
  "bucket": "company-release-artifacts",
  "key": "releases/2026-08-16/manifest.json",
  "contentText": "{\"status\":\"approved\",\"release\":\"2026-08-16\"}",
  "contentType": "application/json",
  "metadata": {
    "release": "2026-08-16",
    "workflow": "approved-publication"
  }
}

Expected result shape:

{
  "status": "success",
  "operation": "put_object",
  "attempts": 1,
  "requestId": "aws-request-reference",
  "data": {
    "bucket": "company-release-artifacts",
    "key": "releases/2026-08-16/manifest.json",
    "contentBytes": 52,
    "overwriteAllowed": false,
    "etag": "provider-etag"
  }
}

Notes

• Pagination: list_objects uses opaque ListObjectsV2 continuations. returnAll=true follows pages only to the fixed AWS S3 destination and stops at limit or 10,000 objects.
• Rate limits: HTTP 408, 429, 500, 502, 503, and 504 plus network failures can retry for read-only operations, bounded by RetryPolicy.maxAttempts from 1 through 5. AWS SDK retries are disabled so writes are exactly one provider attempt.
• API limits: one execution uploads or downloads at most 5 MiB. Multipart upload, ranged download, object tagging, ACL mutation, bucket policy, version listing, batch delete, presigned URLs, S3-compatible custom endpoints, Glacier restore, and event notification configuration are deferred.
• Idempotency: put_object uses If-None-Match: * unless confirmOverwrite=true. Creates and deletes have no caller idempotency key; after any ambiguous provider response, reconcile by bucket/key and request ID before replaying.
• Destructive behavior: bucket and object deletion require explicit confirmation and are never automatically retried. Versioned buckets may retain prior object versions according to AWS configuration.
• Data handling: object content is classified as confidential and sent only to the selected AWS S3 region endpoint. Secret-like metadata names are rejected.
• Provider verification boundary: deterministic tests cover validation, credential isolation, request mapping, pagination, retry boundaries, output normalization, redaction, and discovery. Live AWS behavior remains unverified until an authorized S3 credential and reviewed test bucket are supplied.
• Functional reference: n8n's current AWS S3 connector models bucket and object create/list/read/upload/delete operations with AWS credentials and ListObjectsV2 pagination. ValkyrAI adds fixed routing, verified IntegrationAccount enforcement, create-only upload by default, bounded content, explicit deletion confirmation, safe output normalization, and read-only retries.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsS3Module through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• Integration Account Console
• AWS S3 integration
• S3 storage architecture
• AWS Fargate Launch ExecModule