> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/en/blob-reference/s3-compatibility) 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](/en/sdks/blob/client#creating-the-client).

<Note>
  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`.
</Note>

## `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.

<Tabs>
  <Tab title="npm">
    ```bash theme={"system"}
    npm install @aws-sdk/client-s3
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"system"}
    yarn add @aws-sdk/client-s3
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={"system"}
    pnpm add @aws-sdk/client-s3
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={"system"}
    bun add @aws-sdk/client-s3
    ```
  </Tab>
</Tabs>

```typescript theme={"system"}
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](/en/blob-reference/s3-compatibility#buckets) and [Keys](/en/blob-reference/s3-compatibility#keys) for how S3 keys map to objects, and [Supported operations](/en/blob-reference/s3-compatibility#supported-operations) for what the gateway accepts.

## `s3Credentials()`

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

```typescript theme={"system"}
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.

<Warning>
  `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.
</Warning>

### 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.

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

API reference: [S3 Credentials](/en/blob-reference/endpoint/s3-credentials).

## Next steps

<CardGroup cols={2}>
  <Card title="Errors" icon="triangle-exclamation" href="/en/sdks/blob/errors">
    Error codes and the retry policy.
  </Card>

  <Card title="S3 compatibility" icon="code" href="/en/blob-reference/s3-compatibility">
    What the S3 gateway supports.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.