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

> Obtenez des identifiants S3 avec s3Credentials() et un S3Client prêt à l'emploi avec s3() pour accéder à Blob Storage via la passerelle compatible S3.

Blob Storage dispose d'une [passerelle compatible S3](/fr/blob-reference/s3-compatibility) qui fonctionne avec n'importe quel client S3. Le SDK vous fournit ses identifiants, ou un `S3Client` prêt à l'emploi issu de l'AWS SDK.

<Note>
  Les deux méthodes nécessitent une **clé API**. Un client créé avec un jeton d'envoi reçoit `403 UPLOAD_TOKEN_NOT_ALLOWED`, et une clé dans un ancien format reçoit `LEGACY_API_KEY`.
</Note>

## `s3()`

`s3()` renvoie un `S3Client` de `@aws-sdk/client-s3`, déjà configuré avec l'endpoint, la région et les identifiants de la passerelle, et avec `forcePathStyle: true`.

`@aws-sdk/client-s3` est une **dépendance pair optionnelle** : installez-la uniquement si vous utilisez `s3()`. Elle est chargée à la demande, de sorte que le SDK lui-même reste sans dépendance.

<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    | Contenu                                 | Accès                                    |
| --------- | --------------------------------------- | ---------------------------------------- |
| `public`  | Objets publics                          | Lecture et écriture                      |
| `private` | Objets privés                           | Lecture et écriture                      |
| `legacy`  | Objets envoyés avant le stockage actuel | Lecture, liste et suppression uniquement |

Voir [Buckets](/fr/blob-reference/s3-compatibility#buckets) et [Clés](/fr/blob-reference/s3-compatibility#clés) pour la correspondance entre les clés S3 et les objets, et [Opérations prises en charge](/fr/blob-reference/s3-compatibility#opérations-prises-en-charge) pour ce que la passerelle accepte.

## `s3Credentials()`

Pour les autres clients S3 (aws-cli, rclone, boto3, ...), `s3Credentials()` renvoie la paire de clés brute :

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

| Champ               | Type              | Description                                                                              |
| ------------------- | ----------------- | ---------------------------------------------------------------------------------------- |
| `access_key_id`     | `string`          | Identifiant de la clé d'accès.                                                           |
| `secret_access_key` | `string`          | Clé d'accès **secrète**.                                                                 |
| `endpoint`          | `string`          | Endpoint de la passerelle.                                                               |
| `region`            | `string`          | Région (`auto`).                                                                         |
| `buckets`           | `string[]`        | `public`, `private` et `legacy`.                                                         |
| `access`            | `{ read, write }` | Ce que la paire peut faire, selon les scopes de la clé API (typé `boolean \| string[]`). |
| `expires_at`        | `string \| null`  | Moment où la clé API, et donc la paire, expire ; `null` si elle n'expire pas.            |

Utilisez l'**adressage de type path-style** avec tout autre client.

<Warning>
  `secret_access_key` donne le même accès que la clé API. Gardez-la sur le serveur et stockez-la comme la clé elle-même. Révoquer ou renouveler la clé API invalide aussi la paire.
</Warning>

### Mise en cache

La paire est déterministe pour une clé API donnée : le SDK la **met donc en cache par instance de client**. `s3Credentials()` et `s3()` appellent l'API une seule fois, et les appels suivants réutilisent le résultat. Un appel échoué n'est pas mis en cache, de sorte que l'appel suivant réessaie.

<Tip>
  La route des identifiants n'accepte que 10 requêtes par heure. Créez un seul client `SquareCloudBlob` et réutilisez-le au lieu d'en créer un par requête.
</Tip>

Référence de l'API : [Identifiants S3](/fr/blob-reference/endpoint/s3-credentials).