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

# Blob Storage API authentication

> Authenticate to the Blob Storage API with an API key or a short-lived upload token in the Authorization header, and pick the scopes each route needs.

Blob Storage accepts two kinds of credentials in the `Authorization` header:

* **API key**: created in your [account settings](https://squarecloud.app/en/account/security). It works on every route, limited by the scopes you give it.
* **Upload token** (`squp_...`): a short-lived token your server mints with [Upload Tokens](/en/blob-reference/endpoint/upload-tokens). It only uploads, so it is safe to hand to a browser.

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

The use of the API is subject to the [Terms of Service](https://squarecloud.app/legal) and the [Acceptable Use Policy](https://squarecloud.app/legal/policy).

<Tip>
  The [Blob SDK](/en/sdks/blob/client) (`@squarecloud/blob`) sends the credential for you and wraps every route of this reference.
</Tip>

## Scopes

An API key carries scopes. Blob Storage reads two of them:

| Scope | Routes |
| - | - |
| `blob:read` | [Object List](/en/blob-reference/endpoint/list), [Object Info](/en/blob-reference/endpoint/info), [Object Download](/en/blob-reference/endpoint/download), [Account Stats](/en/blob-reference/endpoint/stats), [Get Settings](/en/blob-reference/endpoint/settings-get), [List Shares](/en/blob-reference/endpoint/shares-list) |
| `blob:write` | [Object Post](/en/blob-reference/endpoint/post), [Object Update](/en/blob-reference/endpoint/update), [Object Copy](/en/blob-reference/endpoint/copy), [Object Delete](/en/blob-reference/endpoint/delete), every [chunked upload](/en/blob-reference/endpoint/chunked-init) route, [Update Settings](/en/blob-reference/endpoint/settings-put), [Upload Tokens](/en/blob-reference/endpoint/upload-tokens), [Create Share](/en/blob-reference/endpoint/shares-create), [Delete Share](/en/blob-reference/endpoint/shares-delete) |
| either | [S3 Credentials](/en/blob-reference/endpoint/s3-credentials): the pair it returns can write only when the key has `blob:write` |

A key without the scope a route needs gets `403 MISSING_SCOPE`. A key restricted to specific applications has no access to Blob Storage and gets `403 RESOURCE_NOT_ALLOWED`.

<Tip>Give each integration its own key with only the scope it needs. A backend that only serves files needs `blob:read`; a job that only uploads needs `blob:write`.</Tip>

## Upload tokens

An upload token is accepted only on [Object Post](/en/blob-reference/endpoint/post) and the [chunked upload](/en/blob-reference/endpoint/chunked-init) routes. Any other route answers `403 UPLOAD_TOKEN_NOT_ALLOWED`. The token pins the name, prefix, visibility, size and file types chosen when it was minted, and stops working when it expires, when its uses run out, or when the API key that minted it is revoked.

## S3 gateway

S3 tools don't send the API key itself. They sign requests (SigV4) with an access key pair derived from it: get it from [S3 Credentials](/en/blob-reference/endpoint/s3-credentials) and read [S3 compatibility](/en/blob-reference/s3-compatibility).

## Errors

Error responses follow the shape `{ "status": "error", "code": "SOME_CODE" }`, sometimes with a `message` that explains the case. Branch on `code`, never on `message`. The full list is in [Errors](/en/blob-reference/errors).

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

### Global errors

Any Blob route can also return these:

| Code | HTTP | Meaning |
| - | - | - |
| `ACCESS_DENIED` | 401 | The credential is missing or was not recognized (revoked, regenerated or expired). |
| `MISSING_SCOPE` | 403 | The API key lacks the scope this route needs. |
| `RESOURCE_NOT_ALLOWED` | 403 | The API key is restricted to specific applications and cannot use Blob Storage. |
| `UPLOAD_TOKEN_NOT_ALLOWED` | 403 | An upload token was sent to a route that is not an upload route. |
| `RATE_LIMITED` | 429 | A limit was reached: this route's own limit, the account-wide API budget of your plan, or this IP sent too many invalid credentials and is blocked for a short period. Wait and retry. |
| `ROUTE_NOT_FOUND` / `NOT_FOUND` | 404 | The requested route does not exist. |
| `INTERNAL_SERVER_ERROR` | 500 | Unexpected internal failure. Try again later. |

<Card title="Limits and Restrictions" href="/en/api-reference/limitations-and-restrictions">
  Learn about the limits and restrictions of the Square Cloud API.
</Card>


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