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

requerido

La clave de API de tu cuenta. Puedes encontrarla en la configuración de tu cuenta.

Upload Tokens permite que tu servidor emita un token de corta duración que un navegador o una app móvil usa para subir directamente a Blob Storage. El archivo nunca pasa por tu servidor, y tu API key nunca sale de él. Requiere el scope blob:write y un plan de pago. El token va en la cabecera Authorization de Object Post o de las rutas de subida por partes, y no funciona en ningún otro lugar (403 UPLOAD_TOKEN_NOT_ALLOWED). Todo lo que defines al emitirlo queda fijado: el navegador no puede cambiar el nombre, el prefijo, la visibilidad, la expiración ni los metadatos, enviar un archivo más grande ni usar otro tipo de archivo.

Cada subida gasta un uso: una llamada a Object Post, o la apertura de una subida por partes (sus partes y su finalización no gastan más).
Sin name, el navegador lo elige y el nombre siempre recibe un security hash, así que un token filtrado nunca puede reemplazar tus archivos existentes.
El token deja de funcionar cuando se agotan sus usos (401 UPLOAD_TOKEN_USED), cuando expira o cuando se revoca la API key que lo emitió (401 ACCESS_DENIED).

string

Fija el nombre del archivo. Sin él, el navegador envía name en la query.

string

Fija el prefijo. Un navegador que envía uno diferente recibe 403 PREFIX_NOT_ALLOWED.

boolean

Fija la visibilidad.

boolean

Solo con name: false permite que la subida reemplace el archivo con ese nombre. Si no, el nombre siempre recibe un hash.

string | null

Fija la expiración (30d, 6h), o null para ninguna. Menos de 7 días requiere Enterprise.

number

Tamaño máximo del archivo en bytes, de 512 a 10737418240 (10 GiB).

string[]

Extensiones aceptadas, de 1 a 20, en minúsculas y sin el punto (png, tar.gz).

object

Metadatos añadidos a cada archivo subido con el token. Solo Pro y Enterprise.

number

predeterminado:"900"

Cuánto dura el token, de 60 a 3600 segundos.

number

predeterminado:"1"

Cuántas subidas permite el token, de 1 a 100.

Límites de tasa

120 tokens por minuto (RATE_LIMITED, 429). Emitir no almacena nada, así que un token por cada subida de usuario final está bien.

Respuesta

string

“success” si tuvo éxito, “error” si no.

object

Mostrar Alternar objeto

string

El token de subida (squp_...). Entrégalo al navegador.

ISO 8601

Cuándo expira el token.

number

Cuántas subidas permite el token.

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

Errores

Código	HTTP	Cuándo
`INVALID_BODY`	400	El cuerpo no es un objeto JSON.
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX` / `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_SECURITY_HASH` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_METADATA`	400	Un valor fijado no es válido.
`INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS` / `INVALID_EXPIRES_IN` / `INVALID_MAX_USES`	400	Un límite está fuera de rango.
`UPLOAD_TOKEN_TOO_LARGE`	400	Demasiadas opciones para un token. Acorta los metadatos o la lista de extensiones.
`PERMISSION_DENIED`	401	La cuenta no tiene un plan de pago activo.
`UPGRADE_REQUIRED`	403	La expiración o los metadatos requieren un plan superior.
`RATE_LIMITED`	429	Más de 120 tokens en un minuto.

Cuando el navegador sube: 401 UPLOAD_TOKEN_USED (usos agotados), 401 ACCESS_DENIED (expirado o revocado), 403 PREFIX_NOT_ALLOWED (otro prefijo), 400 FILE_TYPE_NOT_ALLOWED (extensión no permitida) y 413 FILE_TOO_LARGE (supera 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
  }
}

Primeros Pasos

Objetos

Subida en Partes

Cuenta

Enlaces Compartidos

S3

Límites de tasa

Respuesta

Errores

​Límites de tasa

​Respuesta

​Errores

Límites de tasa

Respuesta

Errores