Blob SDK: S3 gateway client

Get S3 credentials with s3Credentials() and a ready-to-use S3Client with s3() to reach Blob Storage through the S3-compatible gateway.

Blob Storage has an S3-compatible gateway that works with any S3 client. The SDK gives you its credentials, or a ready S3Client from the AWS SDK.

Examples use the blob client from Creating the client.

Both methods need an API key. A client created with an upload token gets 403 UPLOAD_TOKEN_NOT_ALLOWED, and a key in an old format gets LEGACY_API_KEY.

s3()

s3() returns an S3Client from @aws-sdk/client-s3, already configured with the gateway’s endpoint, region and credentials, and with forcePathStyle: true.

@aws-sdk/client-s3 is an optional peer dependency: install it only if you use s3(). It is loaded lazily, so the SDK itself stays dependency-free.

npm

npm install @aws-sdk/client-s3

yarn

yarn add @aws-sdk/client-s3

pnpm

pnpm add @aws-sdk/client-s3

bun

bun add @aws-sdk/client-s3

import { ListObjectsV2Command } from "@aws-sdk/client-s3";
import { SquareCloudBlob } from "@squarecloud/blob";

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
const s3 = await blob.s3();

const { Contents } = await s3.send(new ListObjectsV2Command({ Bucket: "public" }));

Buckets

Bucket	Contents	Access
public	Public objects	Read and write
private	Private objects	Read and write
legacy	Objects uploaded before the current storage	Read, list and delete only

See Buckets and Keys for how S3 keys map to objects, and Supported operations for what the gateway accepts.

s3Credentials()

For other S3 clients (aws-cli, rclone, boto3, …), s3Credentials() returns the raw key pair:

const credentials = await blob.s3Credentials();

Field	Type	Description
access_key_id	string	Access key id.
secret_access_key	string	Secret access key.
endpoint	string	Gateway endpoint.
region	string	Region (auto).
buckets	string[]	public, private and legacy.
access	{ read, write }	What the pair may do, following the API key’s scopes (typed boolean | string[]).
expires_at	string | null	When the API key, and so the pair, expires; null when it does not.

Use path-style addressing with any other client.

secret_access_key gives the same access as the API key. Keep it on the server and store it like the key itself. Revoking or rotating the API key also kills the pair.

Caching

The pair is deterministic per API key, so the SDK caches it per client instance: s3Credentials() and s3() call the API once, and later calls reuse the result. A failed call is not cached, so the next call tries again.

The credentials route accepts only 10 requests per hour. Create one SquareCloudBlob client and reuse it instead of creating one per request.

API reference: S3 Credentials.

Next steps

Errors

Error codes and the retry policy.

S3 compatibility

What the S3 gateway supports.