Amazon S3

Connect a general-purpose S3 bucket with a cross-account IAM role. This is a role in your AWS account that Etchv is allowed to use. Etchv gets short-lived credentials from it, so you don't share an AWS access key.

Create a limited role

Name the role with the prefix etchv-storage-, such as etchv-storage-production. Grant access only to your destination prefix:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:PutObject", "s3:GetObject"],
    "Resource": "arn:aws:s3:::YOUR_BUCKET/etchv/*"
  }]
}

Replace the bucket and prefix. Etchv does not need DeleteObject, ListBucket or ACL permissions. If the bucket uses a customer-managed KMS key for encryption, also grant kms:GenerateDataKey and kms:Decrypt. The key policy must allow this access too.

Add the destination

Use Dashboard storage or an owner/admin key with storage:write:

curl -X POST https://api.etchv.com/storage/destinations \
  -H "X-API-Key: $ETCHV_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Production S3","provider":"s3","bucket":"YOUR_BUCKET",
       "region":"us-east-1","prefix":"etchv","visibility":"private",
       "role_arn":"arn:aws:iam::YOUR_ACCOUNT_ID:role/etchv-storage-production"}'

The response includes id, aws_principal_arn and a unique external_id. Copy these exact values into your role’s trust policy. The trust policy says who may use the role:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"AWS": "RETURNED_AWS_PRINCIPAL_ARN"},
    "Action": "sts:AssumeRole",
    "Condition": {"StringEquals": {"sts:ExternalId": "RETURNED_EXTERNAL_ID"}}
  }]
}

Keep the external ID condition exactly as returned. It stops other Etchv customers from using your connection. See AWS third-party role access.

Test and use

1. Click Test connection, or POST /storage/destinations/{id}/verify. Etchv writes and reads a small test file (a probe) under your prefix.
2. Fix any trust or permission error, then verify again.
3. Pass the destination ID in your embedding request.

Etchv uses your bucket’s default encryption. It never changes your bucket policy or ACLs. Conditional writes stop Etchv from overwriting objects that already exist. When a write is retried, Etchv checks the stored bytes before accepting them.