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

# S3

> Ottieni le credenziali S3 con s3Credentials() e un S3Client pronto all'uso con s3() per accedere a Blob Storage tramite il gateway compatibile con S3.

Blob Storage ha un [gateway compatibile con S3](/it/blob-reference/s3-compatibility) che funziona con qualsiasi client S3. L'SDK ti fornisce le sue credenziali, oppure un `S3Client` già pronto dell'AWS SDK.

<Note>
  Entrambi i metodi richiedono una **chiave API**. Un client creato con un token di upload riceve `403 UPLOAD_TOKEN_NOT_ALLOWED`, e una chiave in un vecchio formato riceve `LEGACY_API_KEY`.
</Note>

## `s3()`

`s3()` restituisce un `S3Client` di `@aws-sdk/client-s3`, già configurato con l'endpoint, la regione e le credenziali del gateway, e con `forcePathStyle: true`.

`@aws-sdk/client-s3` è una **peer dependency opzionale**: installala solo se usi `s3()`. Viene caricata in modo lazy, così l'SDK stesso resta privo di dipendenze.

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

### Bucket

| Bucket    | Contenuto                                    | Accesso                              |
| --------- | -------------------------------------------- | ------------------------------------ |
| `public`  | Oggetti pubblici                             | Lettura e scrittura                  |
| `private` | Oggetti privati                              | Lettura e scrittura                  |
| `legacy`  | Oggetti caricati prima dello storage attuale | Solo lettura, elenco ed eliminazione |

Vedi [Bucket](/it/blob-reference/s3-compatibility#bucket) e [Chiavi](/it/blob-reference/s3-compatibility#chiavi) per come le chiavi S3 corrispondono agli oggetti, e [Operazioni supportate](/it/blob-reference/s3-compatibility#operazioni-supportate) per ciò che il gateway accetta.

## `s3Credentials()`

Per altri client S3 (aws-cli, rclone, boto3, ...), `s3Credentials()` restituisce la coppia di chiavi grezza:

```typescript theme={"system"}
const credentials = await blob.s3Credentials();
```

| Campo               | Tipo              | Descrizione                                                                                     |
| ------------------- | ----------------- | ----------------------------------------------------------------------------------------------- |
| `access_key_id`     | `string`          | Id della chiave di accesso.                                                                     |
| `secret_access_key` | `string`          | Chiave di accesso **segreta**.                                                                  |
| `endpoint`          | `string`          | Endpoint del gateway.                                                                           |
| `region`            | `string`          | Regione (`auto`).                                                                               |
| `buckets`           | `string[]`        | `public`, `private` e `legacy`.                                                                 |
| `access`            | `{ read, write }` | Cosa può fare la coppia, in base agli scope della chiave API (tipizzato `boolean \| string[]`). |
| `expires_at`        | `string \| null`  | Quando scade la chiave API, e quindi la coppia; `null` se non scade.                            |

Usa l'**indirizzamento path-style** con qualsiasi altro client.

<Warning>
  `secret_access_key` concede lo stesso accesso della chiave API. Tienila sul server e conservala come la chiave stessa. Revocare o rigenerare la chiave API invalida anche la coppia.
</Warning>

### Cache

La coppia è deterministica per chiave API, quindi l'SDK la **memorizza in cache per ogni istanza del client**: `s3Credentials()` e `s3()` chiamano l'API una sola volta, e le chiamate successive riutilizzano il risultato. Una chiamata fallita non viene memorizzata in cache, quindi la chiamata successiva riprova.

<Tip>
  La route delle credenziali accetta solo 10 richieste all'ora. Crea un solo client `SquareCloudBlob` e riutilizzalo invece di crearne uno per ogni richiesta.
</Tip>

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