S3 Compatibility

K3’s HTTP gateway speaks native S3 on the byte plane. Point any S3 SDK at it with your Dodil service-account credentials and existing code works — aws s3 sync, boto3.client('s3'), @aws-sdk/client-s3, MinIO mc — no code changes beyond the endpoint URL.

What this page covers: credentials, supported operations, auth modes, and end-to-end setup for the four most common clients.

Credentials & endpoint

Single source of credentials: your Dodil service account. The same <service_account_id> / <service_account_secret> pair you pass to dodil login doubles as your S3 access-key / secret-key — both are issued by Dodil IAM.

Bearer JWT also works on the byte plane (see Auth modes below) if you don’t have SigV4 credentials handy — but SigV4 is what every standard S3 SDK speaks.

Setup — pick your client

# One-time configuration
aws configure --profile dodil-k3
# AWS Access Key ID:     <service_account_id>
# AWS Secret Access Key: <service_account_secret>
# Default region name:   us-east-1
# Default output format: json
 
# Test
aws s3 ls \
  --endpoint-url https://k3.dev.dodil.io \
  --profile dodil-k3

export AWS_PROFILE=dodil-k3
export AWS_ENDPOINT_URL=https://k3.dev.dodil.io   # aws-cli v2.15+
 
aws s3 ls
aws s3 cp ./hello.txt s3://kb-prod/greetings/hello.txt

import boto3
from botocore.config import Config
 
s3 = boto3.client(
    "s3",
    endpoint_url="https://k3.dev.dodil.io",
    aws_access_key_id="<service_account_id>",
    aws_secret_access_key="<service_account_secret>",
    region_name="us-east-1",
    config=Config(s3={"addressing_style": "path"}),
)
 
# Verify
s3.list_buckets()
 
# Upload
s3.upload_file("hello.txt", "kb-prod", "greetings/hello.txt")
 
# Presign a 1-hour download URL
url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "kb-prod", "Key": "greetings/hello.txt"},
    ExpiresIn=3600,
)

import {
  S3Client,
  ListBucketsCommand,
  PutObjectCommand,
  GetObjectCommand,
} from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 
const s3 = new S3Client({
  endpoint: "https://k3.dev.dodil.io",
  region: "us-east-1",
  forcePathStyle: true,
  credentials: {
    accessKeyId: "<service_account_id>",
    secretAccessKey: "<service_account_secret>",
  },
});
 
// Verify
await s3.send(new ListBucketsCommand({}));
 
// Upload
await s3.send(new PutObjectCommand({
  Bucket: "kb-prod",
  Key: "greetings/hello.txt",
  Body: "hello, k3",
  ContentType: "text/plain",
}));
 
// Presign a 1-hour download URL
const url = await getSignedUrl(
  s3,
  new GetObjectCommand({ Bucket: "kb-prod", Key: "greetings/hello.txt" }),
  { expiresIn: 3600 },
);

mc alias set dodil-k3 \
  https://k3.dev.dodil.io \
  <service_account_id> \
  <service_account_secret> \
  --api S3v4 --path on
 
mc ls dodil-k3
mc cp ./hello.txt dodil-k3/kb-prod/greetings/hello.txt
mc share download --expire 1h dodil-k3/kb-prod/greetings/hello.txt

What’s supported

K3 implements the S3 surface needed for production object storage and ingest. Anything not in the tables below is out of scope — K3 does not currently support object versioning, lifecycle / expiration policies, replication, SQS/SNS event notifications, customer-managed encryption keys, or object lock.

Object operations

Bucket operations

Not supported

Auth modes accepted on the byte plane

Region from the credential scope (…/<yyyymmdd>/<region>/s3/aws4_request) is whatever the client picks — K3 derives the signing key from it, so any consistent region works.

End-to-end: aws-cli ↔ dodil k3

Objects uploaded via raw S3 are first-class K3 objects — admin RPCs see them, pipelines fire on them, presigned URLs work over them.

# 1. Create a bucket via S3 (equivalent to `dodil k3 bucket create`)
aws s3 mb s3://kb-s3-demo
 
# 2. Upload an object
echo "hello from aws-cli" > hello.txt
aws s3 cp hello.txt s3://kb-s3-demo/greetings/hello.txt
 
# 3. Inspect via K3 admin — same object, enriched with ingest status
dodil k3 object show greetings/hello.txt -b kb-s3-demo -o json
 
# 4. Issue a K3-signed share URL (shorter than SigV4 presign)
dodil k3 object url greetings/hello.txt -b kb-s3-demo --expires 3600

The takeaway: S3 in, K3 features out. You don’t have to choose a side — buckets are interoperable.

Error response shape

S3-style errors come back as XML on the byte plane (compatible with every S3 SDK), JSON envelope on the admin plane. The two most common byte-plane errors:

<!-- 403 — storage quota exhausted, ACL denial, or auth failure -->
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>AccessDenied</Code>
  <Message>access denied</Message>
</Error>

<!-- 404 — bucket or key not found -->
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>

Standard SDKs surface these as typed exceptions (ClientError in boto3, S3ServiceException in the JS SDK). For admin RPCs (dodil k3 ... / gRPC), see Conventions for the JSON error envelope.

Next steps

• Recipes — direct-from-browser upload, multipart for large files, static-site hosting
• API Reference — gRPC + HTTP admin contracts
• Pipelines — auto-indexing on upload (the K3-specific feature S3 doesn’t have)
• Auth and Access — auth-mode internals