Use the S3 API
Object traffic uses https://storage.cloud.comwit.io, not the JSON platform
API. The gateway authorizes the Comwit token, checks project/bucket access, and
re-signs the same S3 request with private provider credentials.
JavaScript and TypeScript
Section titled “JavaScript and TypeScript”Install the standard AWS client:
pnpm add @aws-sdk/client-s3Create the client in a server-only module:
import "server-only";import { S3Client } from "@aws-sdk/client-s3";
export const storage = new S3Client({ endpoint: process.env.COMWIT_STORAGE_ENDPOINT!, region: "auto", forcePathStyle: true, credentials: { accessKeyId: "comwit", secretAccessKey: "comwit", sessionToken: process.env.COMWIT_STORAGE_TOKEN!, },});The access key and secret are non-secret placeholders required by the S3 SDK.
The actual credential is the cwt_ or cwp_ token in sessionToken. Path-style
addressing is required so the bucket stays in the request path.
Upload and read an object:
import { GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";import { storage } from "./storage";
const bucket = process.env.COMWIT_STORAGE_BUCKET!;
await storage.send(new PutObjectCommand({ Bucket: bucket, Key: "products/desk.png", Body: bytes, ContentType: "image/png",}));
const result = await storage.send(new GetObjectCommand({ Bucket: bucket, Key: "products/desk.png",}));Supported S3 surface
Section titled “Supported S3 surface”The gateway follows R2’s S3-compatible contract, while keeping bucket creation and deletion in the Comwit control plane. The current authenticated surface is:
| Area | Operations |
|---|---|
| Bucket discovery | ListBuckets (filtered to authorized Storage), HeadBucket, GetBucketLocation |
| Object listing | ListObjects, ListObjectsV2 |
| Objects | HeadObject, GetObject, PutObject, DeleteObject, DeleteObjects |
| Server-side copy | CopyObject; the token needs read access to the source and write access to the destination |
| Multipart | create, upload part, upload-part copy, list uploads/parts, complete, and abort |
| Bucket configuration | get/put/delete CORS, get/put lifecycle, get encryption |
Unsupported requests return the S3-shaped 501 NotImplemented response instead
of being forwarded blindly. In particular, use the Comwit CLI, console, or JSON
API for CreateBucket and DeleteBucket. The product promise is R2-compatible
behavior for the enabled surface, not every AWS-only S3 service or extension.
AWS CLI
Section titled “AWS CLI”Use placeholder key material and put the Comwit token in the session-token variable:
export AWS_ACCESS_KEY_ID=comwitexport AWS_SECRET_ACCESS_KEY=comwitexport AWS_SESSION_TOKEN="$COMWIT_STORAGE_TOKEN"export AWS_DEFAULT_REGION=auto
aws s3api list-objects-v2 \ --endpoint-url https://storage.cloud.comwit.io \ --bucket "$COMWIT_STORAGE_BUCKET"Avoid shell tracing and CI debug modes while these variables are present.
Authorization behavior
Section titled “Authorization behavior”- a missing or invalid Comwit token is rejected;
- a valid token without the required Storage scope returns access denied;
- a token cannot name a bucket owned by another project;
ListBucketsreturns only authorized Comwit Storage resources;CreateBucketandDeleteBucketare not the resource lifecycle API.
Use the CLI, console, or Scalar API reference for lifecycle changes.
Browser code
Section titled “Browser code”Do not construct this client in a Client Component. For browser upload/download, follow Public delivery and presigned URLs.