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

> Obtén credenciales S3 con s3Credentials() y un S3Client listo para usar con s3() para acceder a Blob Storage a través del gateway compatible con S3.

Blob Storage tiene un [gateway compatible con S3](/es/blob-reference/s3-compatibility) que funciona con cualquier cliente S3. El SDK te da sus credenciales, o un `S3Client` del AWS SDK ya preparado.

<Note>
  Ambos métodos necesitan una **clave de API**. Un cliente creado con un token de subida recibe `403 UPLOAD_TOKEN_NOT_ALLOWED`, y una clave en un formato antiguo recibe `LEGACY_API_KEY`.
</Note>

## `s3()`

`s3()` devuelve un `S3Client` de `@aws-sdk/client-s3`, ya configurado con el endpoint, la región y las credenciales del gateway, y con `forcePathStyle: true`.

`@aws-sdk/client-s3` es una **peer dependency opcional**: instálala solo si usas `s3()`. Se carga de forma diferida, así que el propio SDK sigue sin dependencias.

<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    | Contenido                                       | Acceso                              |
| --------- | ----------------------------------------------- | ----------------------------------- |
| `public`  | Objetos públicos                                | Lectura y escritura                 |
| `private` | Objetos privados                                | Lectura y escritura                 |
| `legacy`  | Objetos subidos antes del almacenamiento actual | Solo lectura, listado y eliminación |

Consulta [Buckets](/es/blob-reference/s3-compatibility#buckets) y [Keys](/es/blob-reference/s3-compatibility#keys) para ver cómo se corresponden las keys de S3 con los objetos, y [Operaciones compatibles](/es/blob-reference/s3-compatibility#operaciones-compatibles) para ver qué acepta el gateway.

## `s3Credentials()`

Para otros clientes S3 (aws-cli, rclone, boto3, ...), `s3Credentials()` devuelve el par de claves sin procesar:

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

| Campo               | Tipo              | Descripción                                                                                         |
| ------------------- | ----------------- | --------------------------------------------------------------------------------------------------- |
| `access_key_id`     | `string`          | Id de la clave de acceso.                                                                           |
| `secret_access_key` | `string`          | Clave de acceso **secreta**.                                                                        |
| `endpoint`          | `string`          | Endpoint del gateway.                                                                               |
| `region`            | `string`          | Región (`auto`).                                                                                    |
| `buckets`           | `string[]`        | `public`, `private` y `legacy`.                                                                     |
| `access`            | `{ read, write }` | Lo que puede hacer el par, según los scopes de la clave de API (tipado como `boolean \| string[]`). |
| `expires_at`        | `string \| null`  | Cuándo caduca la clave de API, y por tanto el par; `null` cuando no caduca.                         |

Usa **direccionamiento de tipo path** (path-style) con cualquier otro cliente.

<Warning>
  `secret_access_key` da el mismo acceso que la clave de API. Mantenlo en el servidor y guárdalo igual que la propia clave. Revocar o rotar la clave de API también invalida el par.
</Warning>

### Caché

El par es determinista para cada clave de API, así que el SDK **lo guarda en caché por instancia de cliente**: `s3Credentials()` y `s3()` llaman a la API una sola vez, y las llamadas posteriores reutilizan el resultado. Una llamada fallida no se guarda en caché, así que la siguiente vuelve a intentarlo.

<Tip>
  La ruta de credenciales solo acepta 10 peticiones por hora. Crea un único cliente `SquareCloudBlob` y reutilízalo en lugar de crear uno por petición.
</Tip>

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