Tokens de Upload Blob

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

obrigatório

A chave da API para sua conta. Você pode encontrá-la nas configurações da conta.

O Tokens de Upload permite que o seu servidor gere um token de curta duração que um navegador ou app mobile usa para fazer upload diretamente para o Blob Storage. O arquivo nunca passa pelo seu servidor, e a sua chave de API nunca sai dele. Exige o escopo blob:write e um plano pago. O token vai no cabeçalho Authorization do Envio de Objeto ou das rotas de upload em partes, e não funciona em nenhum outro lugar (403 UPLOAD_TOKEN_NOT_ALLOWED). Tudo o que você define ao gerá-lo fica fixado: o navegador não pode mudar o nome, o prefixo, a visibilidade, a expiração nem os metadados, enviar um arquivo maior ou usar outro tipo de arquivo.

Cada upload gasta um uso: uma chamada ao Envio de Objeto, ou a abertura de um upload em partes (as partes e a conclusão dele não gastam mais).
Sem um name, o navegador escolhe o nome e ele sempre recebe um security hash, então um token vazado nunca pode substituir os seus arquivos existentes.
O token deixa de funcionar quando os usos se esgotam (401 UPLOAD_TOKEN_USED), quando expira ou quando a chave de API que o gerou é revogada (401 ACCESS_DENIED).

string

Fixa o nome do arquivo. Sem ele, o navegador envia name na query.

string

Fixa o prefixo. Um navegador que envia um prefixo diferente recebe 403 PREFIX_NOT_ALLOWED.

boolean

Fixa a visibilidade.

boolean

Apenas com name: false permite que o upload substitua o arquivo com esse nome. Caso contrário, o nome sempre recebe um hash.

string | null

Fixa a expiração (30d, 6h), ou null para nenhuma. Abaixo de 7 dias exige Enterprise.

number

Tamanho máximo do arquivo em bytes, de 512 a 10737418240 (10 GiB).

string[]

Extensões aceitas, de 1 a 20, em minúsculas e sem o ponto (png, tar.gz).

object

Metadados adicionados a todo arquivo enviado com o token. Somente Pro e Enterprise.

number

padrão:"900"

Por quanto tempo o token dura, de 60 a 3600 segundos.

number

padrão:"1"

Quantos uploads o token permite, de 1 a 100.

Limites de taxa

120 tokens por minuto (RATE_LIMITED, 429). Gerar um token não armazena nada, então um token por upload de usuário final não é problema.

Resposta

string

“success” se bem-sucedida, “error” caso contrário.

object

Mostrar Alternar objeto

string

O token de upload (squp_...). Entregue-o ao navegador.

ISO 8601

Quando o token expira.

number

Quantos uploads o token permite.

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

Erros

Código	HTTP	Quando
`INVALID_BODY`	400	O corpo não é um objeto JSON.
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX` / `INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_SECURITY_HASH` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_METADATA`	400	Um valor fixado é inválido.
`INVALID_MAX_SIZE` / `INVALID_ALLOWED_EXTENSIONS` / `INVALID_EXPIRES_IN` / `INVALID_MAX_USES`	400	Um limite está fora do intervalo.
`UPLOAD_TOKEN_TOO_LARGE`	400	Opções demais para um token. Encurte os metadados ou a lista de extensões.
`PERMISSION_DENIED`	401	A conta não tem um plano pago ativo.
`UPGRADE_REQUIRED`	403	A expiração ou os metadados exigem um plano superior.
`RATE_LIMITED`	429	Mais de 120 tokens em um minuto.

Quando o navegador faz o upload: 401 UPLOAD_TOKEN_USED (usos esgotados), 401 ACCESS_DENIED (expirado ou revogado), 403 PREFIX_NOT_ALLOWED (outro prefixo), 400 FILE_TYPE_NOT_ALLOWED (extensão não permitida) e 413 FILE_TOO_LARGE (acima de 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
  }
}

Primeiros Passos

Objetos

Uploads em Partes

Conta

Links de Compartilhamento

S3

Limites de taxa

Resposta

Erros

​Limites de taxa

​Resposta

​Erros

Limites de taxa

Resposta

Erros