S3 protocol

Your project's storage buckets are reachable through an S3-compatible endpoint. Point any S3 client or tool at your project with a Signature V4 access key — it is protocol translation over the same buckets and objects, not a second store.

Off by default. The S3 endpoint is gated per project and disabled until an operator enables it — ask us to turn it on for your project. While off, the whole S3 surface behaves as if it is not there.

Endpoint

Configure your S3 client with:

Endpoint	`https://<project-ref>.kethosbase.com/storage/v1/s3`
Region	`kethosbase-1` (a fixed label; it carries no meaning but must match the one your key signs with)
Addressing	path-style — force path-style / disable virtual-host addressing, so the bucket is the first path segment

# example with the standard S3 command-line tool
aws --endpoint-url https://<ref>.kethosbase.com/storage/v1/s3 \
    --region kethosbase-1 \
    s3 cp ./photo.jpg s3://avatars/alice.jpg

Buckets map one-to-one to your storage buckets: a bucket you see on the Storage page is the same bucket over S3.

Supported operations

Object and bucket operations, including multipart upload for large objects:

Group	Operations
Objects	PutObject, GetObject (with `Range` and conditional headers), HeadObject, DeleteObject, DeleteObjects (bulk), ListObjectsV2
Buckets	ListBuckets, CreateBucket, DeleteBucket (refused if non-empty)
Multipart	CreateMultipartUpload, UploadPart, CompleteMultipartUpload, AbortMultipartUpload, ListParts, ListMultipartUploads

PutObject overwrites an existing key. The per-object size cap is the same as the rest of storage; use multipart for large uploads. Bucket create and delete require a service-role key (below).

Access keys

Create S3 access keys through the project management API (owner or admin session). The response returns the access key id and its secret once — store the secret then, because it is not kept and cannot be shown again:

GET    /v1/projects/{ref}/s3-credentials
POST   /v1/projects/{ref}/s3-credentials      # returns { access_key_id, secret, … } once
DELETE /v1/projects/{ref}/s3-credentials/{id}

An access key id looks like KB followed by 18 characters. The secret is not stored anywhere: it is derived from the platform master key on demand and re-derived to verify each request, so there is no secret at rest to leak. Each key carries a fixed scope:

Scope	Behaviour
`service_role`	Full access, runs as the project owner and bypasses RLS. Use it only from your own backend.
`session`	Runs under the `authenticated` role with RLS enforced. It requires an end-user access token, passed as the S3 session token (`X-Amz-Security-Token`), and acts as that user.

Requests are authenticated with AWS Signature V4 (AWS4-HMAC-SHA256), verified in constant time, with a ±15-minute clock window. The key's scope comes from the credential record, never from the request, and a key only works within its own project.

Not supported yet

Presigned URLs (query-string Signature V4) — use a Kethosbase signed URL for time-limited link access for now.
Dashboard UI for S3 keys — keys are managed through the API above; a console screen is planned.

Because a key's secret is derived from the platform master key, rotating that master key invalidates every S3 secret. Revoking a single key takes effect within about a minute (a short credential-cache window).