Create an upload token

Mint a short-lived upload token with POST /v1/upload-tokens so a browser can upload straight to Blob Storage without your API key.

POST /v1/upload-tokens

Server (Node.js)

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

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

Authorization · 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 an active 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).
• In chunked uploads, a token only drives the uploads it opened itself (status, parts, completion and abort): an upload value from another upload answers 400 INVALID_UPLOAD_TOKEN.
• 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, when the API key that minted it is regenerated or revoked, or when the dashboard session that minted it logs out (401 ACCESS_DENIED).

Parameters

name · string

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

prefix · string

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

private · boolean

Pins the visibility.

security_hash · boolean

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

expire · string | null

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

max_size · number

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

allowed_extensions · string[]

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

metadata · object

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

expires_in · number · default: "900"

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

max_uses · 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

status · string

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

response · object

Show properties

token · string

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

expires_at · ISO 8601

When the token expires.

max_uses · number

How many uploads the token allows.

Server (Node.js)

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

{
  "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 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, its key regenerated or revoked, or its session logged out), 403 PREFIX_NOT_ALLOWED (other prefix), 400 FILE_TYPE_NOT_ALLOWED (extension not allowed) and 413 FILE_TOO_LARGE (over max_size).

Related

• Blob SDK: blob.uploadTokens.create()