Skip to main content
Blob Storage accepts two kinds of credentials in the Authorization header:
  • API key: created in your account settings. 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. It only uploads, so it is safe to hand to a browser.
The use of the API is subject to the Terms of Service and the Acceptable Use Policy.
The Blob SDK (@squarecloud/blob) sends the credential for you and wraps every route of this reference.

​
Scopes

An API key carries scopes. Blob Storage reads two of them: 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.
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.

​
Upload tokens

An upload token is accepted only on Object Post and the chunked upload 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 and read 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.

​
Global errors

Any Blob route can also return these:

Limits and Restrictions

Learn about the limits and restrictions of the Square Cloud API.