Blob Upload Tokens

POST

upload-tokens

// Your backend: mint a token for the signed-in user and return it to the page.
const res = await fetch('https://blob.squarecloud.app/v1/upload-tokens', {
  method: 'POST',
  headers: {
    Authorization: process.env.SQUARE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prefix: `avatars/${userId}`,
    allowed_extensions: ['png', 'jpg', 'webp'],
    max_size: 2 * 1024 * 1024,
    expires_in: 300,
  }),
});
const { response } = await res.json();
// send response.token to the browser

const form = new FormData();
form.append('file', input.files[0]);

const res = await fetch('https://blob.squarecloud.app/v1/objects?name=avatar', {
  method: 'POST',
  headers: { Authorization: token },
  body: form,
});
const { response } = await res.json();
// response.url is the public URL of the new file

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/upload-tokens' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "prefix": "avatars", "allowed_extensions": ["png", "jpg"], "max_size": 2097152 }'

{
  "status": "success",
  "response": {
    "token": "squp_Tq7xLm2Vb9Rk4Wz1Nc8Hy5Js0Gd3Fp6Ae.Hq3mZ8vT1kLw9xRb",
    "expires_at": "2026-09-25T12:15:00.000Z",
    "max_uses": 1
  }
}

string

required

The API key for your account. You can find this in your account settings.

Upload Tokens lets your server mint a short-lived token that a browser or mobile app uses to upload directly to Blob Storage. The file never passes through your server, and your API key never leaves it. Requires the blob:write scope and a paid plan. The token goes in the Authorization header of Object Post or the chunked upload routes, and works nowhere else (403 UPLOAD_TOKEN_NOT_ALLOWED). Everything you set when minting it is pinned: the browser can’t change the name, prefix, visibility, expiry or metadata, send a larger file, or use another file type.

Each upload spends one use: a call to Object Post, or opening a chunked upload (its parts and completion don’t spend more).
Without a name, the browser picks it and the name always gets a security hash, so a leaked token can never replace your existing files.
The token stops working when its uses run out (401 UPLOAD_TOKEN_USED), when it expires or when the API key that minted it is revoked (401 ACCESS_DENIED).

string

Pins the file name. Without it, the browser sends name in the query.

string

Pins the prefix. A browser that sends a different one gets 403 PREFIX_NOT_ALLOWED.

boolean

Pins the visibility.

boolean

Only with name: false lets the upload replace the file with that name. Otherwise the name always gets a hash.

string | null

Pins the expiry (30d, 6h), or null for none. Under 7 days needs Enterprise.

number

Maximum file size in bytes, from 512 to 10737418240 (10 GiB).

string[]

Accepted extensions, 1 to 20, lowercase and without the dot (png, tar.gz).

object

Metadata added to every file uploaded with the token. Pro and Enterprise only.

number

default:"900"

How long the token lasts, from 60 to 3600 seconds.

number

default:"1"

How many uploads the token allows, from 1 to 100.

Rate limits

120 tokens per minute (RATE_LIMITED, 429). Minting stores nothing, so one token per end-user upload is fine.

Response

string

“success” if successful, “error” if not.

object

Show Toggle object

string

The upload token (squp_...). Hand it to the browser.

ISO 8601

When the token expires.

number

How many uploads the token allows.

// Your backend: mint a token for the signed-in user and return it to the page.
const res = await fetch('https://blob.squarecloud.app/v1/upload-tokens', {
  method: 'POST',
  headers: {
    Authorization: process.env.SQUARE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prefix: `avatars/${userId}`,
    allowed_extensions: ['png', 'jpg', 'webp'],
    max_size: 2 * 1024 * 1024,
    expires_in: 300,
  }),
});
const { response } = await res.json();
// send response.token to the browser

const form = new FormData();
form.append('file', input.files[0]);

const res = await fetch('https://blob.squarecloud.app/v1/objects?name=avatar', {
  method: 'POST',
  headers: { Authorization: token },
  body: form,
});
const { response } = await res.json();
// response.url is the public URL of the new file

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/upload-tokens' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "prefix": "avatars", "allowed_extensions": ["png", "jpg"], "max_size": 2097152 }'

{
  "status": "success",
  "response": {
    "token": "squp_Tq7xLm2Vb9Rk4Wz1Nc8Hy5Js0Gd3Fp6Ae.Hq3mZ8vT1kLw9xRb",
    "expires_at": "2026-09-25T12:15:00.000Z",
    "max_uses": 1
  }
}

Errors

Code	HTTP	When
`INVALID_BODY`	400	The body is not a JSON object.
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX` / `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_SECURITY_HASH` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_METADATA`	400	A pinned value is invalid.
`INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS` / `INVALID_EXPIRES_IN` / `INVALID_MAX_USES`	400	A limit is out of range.
`UPLOAD_TOKEN_TOO_LARGE`	400	Too many options for one token. Shorten the metadata or the extension list.
`PERMISSION_DENIED`	401	The account has no active paid plan.
`UPGRADE_REQUIRED`	403	The expiry or metadata needs a higher plan.
`RATE_LIMITED`	429	More than 120 tokens in a minute.

When the browser uploads: 401 UPLOAD_TOKEN_USED (used up), 401 ACCESS_DENIED (expired or revoked), 403 PREFIX_NOT_ALLOWED (other prefix), 400 FILE_TYPE_NOT_ALLOWED (extension not allowed) and 413 FILE_TOO_LARGE (over max_size).

// Your backend: mint a token for the signed-in user and return it to the page.
const res = await fetch('https://blob.squarecloud.app/v1/upload-tokens', {
  method: 'POST',
  headers: {
    Authorization: process.env.SQUARE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prefix: `avatars/${userId}`,
    allowed_extensions: ['png', 'jpg', 'webp'],
    max_size: 2 * 1024 * 1024,
    expires_in: 300,
  }),
});
const { response } = await res.json();
// send response.token to the browser

const form = new FormData();
form.append('file', input.files[0]);

const res = await fetch('https://blob.squarecloud.app/v1/objects?name=avatar', {
  method: 'POST',
  headers: { Authorization: token },
  body: form,
});
const { response } = await res.json();
// response.url is the public URL of the new file

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/upload-tokens' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "prefix": "avatars", "allowed_extensions": ["png", "jpg"], "max_size": 2097152 }'

{
  "status": "success",
  "response": {
    "token": "squp_Tq7xLm2Vb9Rk4Wz1Nc8Hy5Js0Gd3Fp6Ae.Hq3mZ8vT1kLw9xRb",
    "expires_at": "2026-09-25T12:15:00.000Z",
    "max_uses": 1
  }
}

Getting Started

Objects

Chunked Uploads

Account

Share Links

S3

Rate limits

Response

Errors

​Rate limits

​Response

​Errors

Rate limits

Response

Errors