Skip to content

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.

Install the standard AWS client:

Terminal window
pnpm add @aws-sdk/client-s3

Create 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",
}));

The gateway follows R2’s S3-compatible contract, while keeping bucket creation and deletion in the Comwit control plane. The current authenticated surface is:

AreaOperations
Bucket discoveryListBuckets (filtered to authorized Storage), HeadBucket, GetBucketLocation
Object listingListObjects, ListObjectsV2
ObjectsHeadObject, GetObject, PutObject, DeleteObject, DeleteObjects
Server-side copyCopyObject; the token needs read access to the source and write access to the destination
Multipartcreate, upload part, upload-part copy, list uploads/parts, complete, and abort
Bucket configurationget/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.

Use placeholder key material and put the Comwit token in the session-token variable:

Terminal window
export AWS_ACCESS_KEY_ID=comwit
export AWS_SECRET_ACCESS_KEY=comwit
export 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.

  • 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;
  • ListBuckets returns only authorized Comwit Storage resources;
  • CreateBucket and DeleteBucket are not the resource lifecycle API.

Use the CLI, console, or Scalar API reference for lifecycle changes.

Do not construct this client in a Client Component. For browser upload/download, follow Public delivery and presigned URLs.