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

# Autenticação na API do Blob Storage

> Autentique-se na API do Blob Storage com uma chave de API ou um token de upload de curta duração no header Authorization, e escolha os escopos de cada rota.

O Blob Storage aceita dois tipos de credencial no cabeçalho `Authorization`:

* **Chave de API**: criada nas [configurações da sua conta](https://squarecloud.app/pt-br/account/security). Funciona em todas as rotas, limitada pelos escopos que você atribuir a ela.
* **Token de upload** (`squp_...`): um token de curta duração que o seu servidor gera com [Tokens de Upload](/pt-br/blob-reference/endpoint/upload-tokens). Ele só faz uploads, então é seguro entregá-lo a um navegador.

```bash theme={"system"}
Authorization: <api_key>
```

O uso da API está sujeito aos [Termos de Serviço](https://squarecloud.app/legal) e à [Política de Uso Aceitável](https://squarecloud.app/legal/policy).

<Tip>
  O [SDK de Blob](/pt-br/sdks/blob/client) (`@squarecloud/blob`) envia a credencial para você e encapsula todas as rotas desta referência.
</Tip>

## Escopos

Uma chave de API carrega escopos. O Blob Storage lê dois deles:

| Escopo | Rotas |
| - | - |
| `blob:read` | [Lista de Objetos](/pt-br/blob-reference/endpoint/list), [Informações do Objeto](/pt-br/blob-reference/endpoint/info), [Download de Objeto](/pt-br/blob-reference/endpoint/download), [Estatísticas da Conta](/pt-br/blob-reference/endpoint/stats), [Obter Configurações](/pt-br/blob-reference/endpoint/settings-get), [Listar Compartilhamentos](/pt-br/blob-reference/endpoint/shares-list) |
| `blob:write` | [Envio de Objeto](/pt-br/blob-reference/endpoint/post), [Atualização de Objeto](/pt-br/blob-reference/endpoint/update), [Cópia de Objeto](/pt-br/blob-reference/endpoint/copy), [Exclusão de Objetos](/pt-br/blob-reference/endpoint/delete), todas as rotas de [upload em partes](/pt-br/blob-reference/endpoint/chunked-init), [Atualizar Configurações](/pt-br/blob-reference/endpoint/settings-put), [Tokens de Upload](/pt-br/blob-reference/endpoint/upload-tokens), [Criar Compartilhamento](/pt-br/blob-reference/endpoint/shares-create), [Excluir Compartilhamento](/pt-br/blob-reference/endpoint/shares-delete) |
| qualquer um | [Credenciais S3](/pt-br/blob-reference/endpoint/s3-credentials): o par retornado só pode gravar quando a chave tem `blob:write` |

Uma chave sem o escopo de que a rota precisa recebe `403 MISSING_SCOPE`. Uma chave restrita a aplicações específicas não tem acesso ao Blob Storage e recebe `403 RESOURCE_NOT_ALLOWED`.

<Tip>Dê a cada integração a sua própria chave, apenas com o escopo de que ela precisa. Um backend que só serve arquivos precisa de `blob:read`; um job que só faz uploads precisa de `blob:write`.</Tip>

## Tokens de upload

Um token de upload só é aceito no [Envio de Objeto](/pt-br/blob-reference/endpoint/post) e nas rotas de [upload em partes](/pt-br/blob-reference/endpoint/chunked-init). Qualquer outra rota responde `403 UPLOAD_TOKEN_NOT_ALLOWED`. O token fixa o nome, o prefixo, a visibilidade, o tamanho e os tipos de arquivo escolhidos quando foi gerado, e deixa de funcionar quando expira, quando seus usos se esgotam ou quando a chave de API que o gerou é revogada.

## Gateway S3

Ferramentas S3 não enviam a chave de API em si. Elas assinam as requisições (SigV4) com um par de chaves de acesso derivado dela: obtenha-o em [Credenciais S3](/pt-br/blob-reference/endpoint/s3-credentials) e leia [Compatibilidade com S3](/pt-br/blob-reference/s3-compatibility).

## Erros

As respostas de erro seguem o formato `{ "status": "error", "code": "SOME_CODE" }`, às vezes com uma `message` que explica o caso. Use `code` na sua lógica, nunca `message`. A lista completa está em [Erros](/pt-br/blob-reference/errors).

```json theme={"system"}
{
    "status": "error",
    "code": "RATE_LIMITED"
}
```

### Erros globais

Qualquer rota do Blob também pode retornar estes:

| Código | HTTP | Significado |
| - | - | - |
| `ACCESS_DENIED` | 401 | A credencial está ausente ou não foi reconhecida (revogada, regenerada ou expirada). |
| `MISSING_SCOPE` | 403 | A chave de API não tem o escopo de que esta rota precisa. |
| `RESOURCE_NOT_ALLOWED` | 403 | A chave de API está restrita a aplicações específicas e não pode usar o Blob Storage. |
| `UPLOAD_TOKEN_NOT_ALLOWED` | 403 | Um token de upload foi enviado a uma rota que não é de upload. |
| `RATE_LIMITED` | 429 | Um limite foi atingido: o limite próprio desta rota, o orçamento de API da conta inteira no seu plano, ou este IP enviou credenciais inválidas demais e está bloqueado por um curto período. Aguarde e tente novamente. |
| `ROUTE_NOT_FOUND` / `NOT_FOUND` | 404 | A rota solicitada não existe. |
| `INTERNAL_SERVER_ERROR` | 500 | Falha interna inesperada. Tente novamente mais tarde. |

<Card title="Limites e Restrições" href="/pt-br/api-reference/limitations-and-restrictions">
  Conheça os limites e restrições da API da Square Cloud.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.