S3 Adapter

Use the S3 Adapter when an agent or AWS-compatible tool needs bucket and object access without receiving the upstream access key. The agent signs ordinary SigV4 requests with temporary APIZ-issued AWS-shaped credentials; APIZ verifies them, evaluates Policy, and signs the upstream request separately.

What This Adapter Supports

• AWS S3, Cloudflare R2, MinIO, and other S3-compatible HTTPS endpoints.
• AWS access key, secret key, and optional upstream session token.
• APIZ-issued access key, secret key, and required session token.
• Bucket, prefix, object, multipart, tagging, ACL, and version-list actions.
• AWS CLI/SDK endpoint override and path-style addressing.
• Bounded streaming uploads and SigV4 header or presigned-query verification.

Credential Boundary

Two complete AWS credential sets exist:

APIZ never forwards the agent's SigV4 authorization upstream. It verifies the APIZ signature and session token, applies Policy, then signs with the protected upstream credential.

Prepare The Upstream Credential

Create provider credentials restricted to the intended bucket and prefix. Collect:

• provider preset;
• endpoint URL;
• signing region;
• whether path-style addressing is required;
• default test bucket and prefix; and
• upstream access key, secret access key, and optional session token.

For AWS, use the bucket's actual region and matching Regional S3 endpoint. For R2, use the account-specific S3 endpoint and its required signing region. For MinIO, path-style access is normally required.

Web Console

1. Open API Instances → Create API Instance → S3.
2. Enter the upstream access key and secret under S3 credentials.
3. Select the provider, endpoint, and signing region.
4. Add an optional default bucket and prefix for tests and Policy review.
5. Enable Force path-style addressing when required by the endpoint.
6. Start with Head bucket, List objects, or Head object.
7. Attach Allow S3 read operations for read-only agent access, test, and save.

Write and delete tests operate on the configured service. Use only a dedicated synthetic object key and understand that APIZ does not automatically restore it.

CLI

apiz adapter explain s3

read -rsp "S3 access key ID: " S3_ACCESS_KEY && printf '\n'
read -rsp "S3 secret access key: " S3_SECRET_KEY && printf '\n'
jq -n --arg access "$S3_ACCESS_KEY" --arg secret "$S3_SECRET_KEY" \
  '{access_key_id:$access,secret_access_key:$secret}' |
apiz -o json api create \
  --adapter s3 \
  --name artifact-bucket \
  --config-json '{"provider":"aws_s3","endpoint_url":"https://s3.us-west-2.amazonaws.com","region":"us-west-2","bucket":"example-artifacts","default_prefix":"agent/"}' \
  --test-config-json '{"preset":"head_bucket","bucket":"example-artifacts"}' \
  --credential-stdin
unset S3_ACCESS_KEY S3_SECRET_KEY

Replace the synthetic bucket with one the upstream credential can access. Add session_token to the credential JSON when the provider issued temporary upstream credentials.

Give An Agent Access

apiz -o json client create --name artifact-agent
apiz client bind <client-id> --api-instance <api-instance-id> --alias artifacts
umask 077
apiz -o json client credentials create <client-id> \
  --binding artifacts --ttl 1h --format aws-credentials > setup.json

The setup result includes an APIZ endpoint, region, access key ID, secret access key, and session token. All are agent-facing APIZ values, not the upstream credential. Together they form the agent's Temporary Credential. Remove setup.json after securely transferring the required item.

The S3 adapter owns Shell/dotenv AWS variables and AWS profile rendering. A single selected S3 item exports APIZ_S3_ENDPOINT from that item's selected connection, alongside its applicable AWS variables. It does not use the Manifest's global S3 URL as a fallback. Multiple S3 items retain distinct namespaced variables and profiles and omit ambiguous global endpoints. S3 configuration is absent when only another adapter is selected.

Use It From The Agent

Load the values from the Setup Manifest and use the generated APIZ endpoint:

AWS_ACCESS_KEY_ID=$(jq -r '.items[0].auth.access_key_id' setup.json)
AWS_SECRET_ACCESS_KEY=$(jq -r '.items[0].auth.secret_access_key' setup.json)
AWS_SESSION_TOKEN=$(jq -r '.items[0].auth.session_token' setup.json)
AWS_REGION=$(jq -r '.items[0].auth.region' setup.json)
APIZ_S3_ENDPOINT=$(jq -r '.items[0].endpoint' setup.json)
export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_REGION

aws --endpoint-url "$APIZ_S3_ENDPOINT" s3api list-objects-v2 \
  --bucket example-artifacts --prefix agent/ --max-keys 10

Use the same endpoint override and temporary values with an AWS SDK. The session token is required; omitting it causes APIZ credential verification to fail.

Choose A Connection After Issuance

Create credentials from the Client page after reviewing APIs and expiry. The result provides Copy APIZ token independently of the service configuration. Choose the API, a compatible Connection (Path or Domain Routing), and format before copying configuration. This reuses the same credentials and expiry.

For remote use, inject the token as APIZ_TOKEN and the public endpoint as APIZ_PROXY_URL. apiz client handoff setup --format json returns prepared items and their connection ids. Use --connection item_id=connection_id with handoff setup or client setup render to select one. Values come from that manifest, not guessed adapter names. Old groups without connection snapshots retain their original endpoint. Changing an S3 endpoint requires signing a new request; never edit the hostname of an already signed URL.

Policy Actions And Resources

Resources are s3_bucket, s3_prefix, and s3_object. Important actions:

The Allow S3 read operations template covers common metadata, list, and object reads and denies writes/deletes. Add bucket and prefix resource conditions when the upstream credential spans more storage than the agent needs. apiz adapter explain s3 returns the exact deployed action aliases.

Connection Tests

Use the first three for routine validation. The write/delete presets are explicitly destructive and should target only a dedicated test key.

Evidence And Troubleshooting

• s3_region_mismatch: set the reported bucket region and use the suggested AWS Regional endpoint.
• s3_endpoint_region_mismatch: region matches, but the endpoint does not; accept the suggested endpoint only after verifying the target.
• Signature failure at APIZ: verify the APIZ endpoint, region, access key, secret, session token, and local clock. Do not substitute upstream keys.
• Upstream access denied: APIZ allowed the request, but the protected upstream credential or provider policy rejected the operation.
• SignatureDoesNotMatch with an upstream_result 403 after an allow decision is an upstream-signing failure, not evidence that the temporary client key failed APIZ validation. APIZ strips inbound CDN/forwarding metadata before re-signing so a later edge hop cannot invalidate that signature by rewriting those headers. Check the deployed version and upstream configuration before replacing client credentials; do not disable signature validation.
• Policy denial: inspect bucket, prefix/key, normalized S3 action, and whether multipart or tagging changed the action.

Use request evidence to distinguish agent-signature, Policy, Secret Broker, and upstream failures.

Current Limitations

• Path-style bucket addressing is supported; virtual-host-style bucket routing is not currently supported.
• The documented public endpoint must be configured for the deployment before S3 Setup Manifest items can be generated.
• Maximum decoded upload size and request timeouts are bounded by API Instance transport settings; large transfers are not unbounded pass-through.
• Provider-specific features outside the normalized catalog may be rejected or receive a coarser action until the adapter is extended.