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

> Obtenha credenciais S3 com s3Credentials() e um S3Client pronto para uso com s3() para acessar o Blob Storage pelo gateway compatível com S3.

O Blob Storage tem um [gateway compatível com S3](/pt-br/blob-reference/s3-compatibility) que funciona com qualquer cliente S3. O SDK fornece as credenciais dele, ou um `S3Client` pronto do AWS SDK.

<Note>
  Ambos os métodos precisam de uma **chave de API**. Um cliente criado com um token de upload recebe `403 UPLOAD_TOKEN_NOT_ALLOWED`, e uma chave em formato antigo recebe `LEGACY_API_KEY`.
</Note>

## `s3()`

`s3()` retorna um `S3Client` do `@aws-sdk/client-s3`, já configurado com o endpoint, a região e as credenciais do gateway, e com `forcePathStyle: true`.

`@aws-sdk/client-s3` é uma **peer dependency opcional**: instale-a apenas se você usar `s3()`. Ela é carregada sob demanda, então o SDK em si continua sem dependências.

<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    | Conteúdo                                      | Acesso                              |
| --------- | --------------------------------------------- | ----------------------------------- |
| `public`  | Objetos públicos                              | Leitura e escrita                   |
| `private` | Objetos privados                              | Leitura e escrita                   |
| `legacy`  | Objetos enviados antes do armazenamento atual | Apenas leitura, listagem e exclusão |

Veja [Buckets](/pt-br/blob-reference/s3-compatibility#buckets) e [Chaves](/pt-br/blob-reference/s3-compatibility#chaves) para saber como as chaves S3 correspondem aos objetos, e [Operações suportadas](/pt-br/blob-reference/s3-compatibility#operações-suportadas) para o que o gateway aceita.

## `s3Credentials()`

Para outros clientes S3 (aws-cli, rclone, boto3, ...), `s3Credentials()` retorna o par de chaves bruto:

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

| Campo               | Tipo              | Descrição                                                                                        |
| ------------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
| `access_key_id`     | `string`          | Id da chave de acesso.                                                                           |
| `secret_access_key` | `string`          | Chave de acesso **secreta**.                                                                     |
| `endpoint`          | `string`          | Endpoint do gateway.                                                                             |
| `region`            | `string`          | Região (`auto`).                                                                                 |
| `buckets`           | `string[]`        | `public`, `private` e `legacy`.                                                                  |
| `access`            | `{ read, write }` | O que o par pode fazer, seguindo os escopos da chave de API (tipado como `boolean \| string[]`). |
| `expires_at`        | `string \| null`  | Quando a chave de API, e portanto o par, expira; `null` quando não expira.                       |

Use **endereçamento path-style** com qualquer outro cliente.

<Warning>
  `secret_access_key` dá o mesmo acesso que a chave de API. Mantenha-a no servidor e armazene-a como a própria chave. Revogar ou rotacionar a chave de API também invalida o par.
</Warning>

### Cache

O par é determinístico por chave de API, então o SDK **o armazena em cache por instância do cliente**: `s3Credentials()` e `s3()` chamam a API uma vez, e as chamadas seguintes reutilizam o resultado. Uma chamada que falha não é armazenada em cache, então a próxima chamada tenta novamente.

<Tip>
  A rota de credenciais aceita apenas 10 requisições por hora. Crie um único cliente `SquareCloudBlob` e reutilize-o, em vez de criar um por requisição.
</Tip>

Referência da API: [Credenciais S3](/pt-br/blob-reference/endpoint/s3-credentials).