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

> Hol dir S3-Zugangsdaten mit s3Credentials() und einen sofort einsatzbereiten S3Client mit s3(), um Blob Storage über das S3-kompatible Gateway zu erreichen.

Blob Storage hat ein [S3-kompatibles Gateway](/de/blob-reference/s3-compatibility), das mit jedem S3-Client funktioniert. Das SDK gibt dir seine Zugangsdaten oder einen fertigen `S3Client` aus dem AWS SDK.

<Note>
  Beide Methoden benötigen einen **API-Schlüssel**. Ein mit einem Upload-Token erstellter Client erhält `403 UPLOAD_TOKEN_NOT_ALLOWED`, und ein Schlüssel in einem alten Format erhält `LEGACY_API_KEY`.
</Note>

## `s3()`

`s3()` gibt einen `S3Client` aus `@aws-sdk/client-s3` zurück, bereits konfiguriert mit Endpoint, Region und Zugangsdaten des Gateways sowie mit `forcePathStyle: true`.

`@aws-sdk/client-s3` ist eine **optionale Peer-Abhängigkeit**: Installiere sie nur, wenn du `s3()` verwendest. Sie wird erst bei Bedarf geladen, sodass das SDK selbst frei von Abhängigkeiten bleibt.

<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    | Inhalt                                                     | Zugriff                          |
| --------- | ---------------------------------------------------------- | -------------------------------- |
| `public`  | Öffentliche Objekte                                        | Lesen und Schreiben              |
| `private` | Private Objekte                                            | Lesen und Schreiben              |
| `legacy`  | Objekte, die vor dem aktuellen Speicher hochgeladen wurden | Nur Lesen, Auflisten und Löschen |

Wie S3-Keys auf Objekte abgebildet werden, erfährst du unter [Buckets](/de/blob-reference/s3-compatibility#buckets) und [Keys](/de/blob-reference/s3-compatibility#keys), und was das Gateway akzeptiert, unter [Unterstützte Operationen](/de/blob-reference/s3-compatibility#unterstützte-operationen).

## `s3Credentials()`

Für andere S3-Clients (aws-cli, rclone, boto3, ...) gibt `s3Credentials()` das rohe Schlüsselpaar zurück:

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

| Feld                | Typ               | Beschreibung                                                                                  |
| ------------------- | ----------------- | --------------------------------------------------------------------------------------------- |
| `access_key_id`     | `string`          | ID des Zugriffsschlüssels.                                                                    |
| `secret_access_key` | `string`          | **Geheimer** Zugriffsschlüssel.                                                               |
| `endpoint`          | `string`          | Endpoint des Gateways.                                                                        |
| `region`            | `string`          | Region (`auto`).                                                                              |
| `buckets`           | `string[]`        | `public`, `private` und `legacy`.                                                             |
| `access`            | `{ read, write }` | Was das Paar darf, gemäß den Scopes des API-Schlüssels (typisiert als `boolean \| string[]`). |
| `expires_at`        | `string \| null`  | Wann der API-Schlüssel und damit das Paar abläuft; `null`, wenn er nicht abläuft.             |

Verwende bei jedem anderen Client **Path-Style-Adressierung**.

<Warning>
  `secret_access_key` gewährt denselben Zugriff wie der API-Schlüssel. Behalte ihn auf dem Server und bewahre ihn wie den Schlüssel selbst auf. Das Widerrufen oder Erneuern des API-Schlüssels macht auch das Paar ungültig.
</Warning>

### Caching

Das Paar ist pro API-Schlüssel deterministisch, daher **cacht das SDK es pro Client-Instanz**: `s3Credentials()` und `s3()` rufen die API einmal auf, und spätere Aufrufe verwenden das Ergebnis wieder. Ein fehlgeschlagener Aufruf wird nicht gecacht, sodass der nächste Aufruf es erneut versucht.

<Tip>
  Die Route für Zugangsdaten akzeptiert nur 10 Anfragen pro Stunde. Erstelle einen einzigen `SquareCloudBlob`-Client und verwende ihn wieder, statt pro Anfrage einen neuen zu erstellen.
</Tip>

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