Uploads

Duas coisas podem ser enviadas: o avatar de um usuário e o logo de uma organização. As duas funcionam igual, e nenhuma manda bytes pela API.

Exige storage compatível com S3 (S3, R2, MinIO). Sem ele as duas rotas respondem 501 uploads_unavailable e GET /v1/session informa uploads_available: false.

O fluxo

Peça uma URL assinada

curl -s $API/v1/account/avatar/upload-url \
  -H "Authorization: Bearer $UK_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{ "content_type": "image/png", "size_bytes": 184320 }'

{
  "upload_url": "https://bucket.example.com/avatars/…?X-Amz-Signature=…",
  "headers": { "Content-Type": "image/png" },
  "public_url": "https://cdn.example.com/avatars/…"
}

Faça o PUT direto no bucket

curl -X PUT "$UPLOAD_URL" \
  -H 'Content-Type: image/png' \
  --data-binary @avatar.png

Envie exatamente os headers que voltaram — eles fazem parte da assinatura.

Salve a URL pública

curl -s -X PATCH $API/v1/account \
  -H "Authorization: Bearer $UK_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{ "avatar_url": "https://cdn.example.com/avatars/…" }'

Salvar é uma chamada separada de propósito. O upload pode falhar no meio, e um perfil apontando para um objeto escrito pela metade seria pior que um ainda apontando para a imagem antiga.

O logo da organização

Idêntico, com duas diferenças: exige organization:update, e a URL é salva com PATCH /v1/organization.

curl -s $API/v1/organization/logo/upload-url \
  -H "Authorization: Bearer $UK_SESSION" \
  -H "X-Organization-Id: org_4b1e…" \
  -H 'Content-Type: application/json' \
  -d '{ "content_type": "image/webp", "size_bytes": 24576 }'

O que é permitido


Tipos	`image/jpeg`, `image/png`, `image/webp`, `image/gif`
Tamanho	1 byte a 5 MiB

Uma allowlist, não uma blocklist — deliberadamente. Esses arquivos são servidos de volta a partir de um host público, e text/html entre eles seria um vetor de XSS armazenado naquele host.

Resposta	Causa
`400 unsupported_type`	Não é um dos quatro tipos de imagem
`400 invalid_size`	`size_bytes` é 0, negativo, ou passa de 5 MiB
`501 uploads_unavailable`	O servidor não tem storage configurado

O tipo e o tamanho fazem parte da assinatura, então é o bucket que os impõe. A verificação no lado da API existe para te dar um erro legível, não para ser a imposição.

Substituindo uma imagem

Cada upload ganha uma chave de objeto aleatória, então substituir uma imagem nunca sobrescreve o objeto antigo. Uma URL em cache num CDN ou num e-mail não pode começar a servir a foto de outra pessoa. O objeto antigo fica para trás. Limpar é um job de manutenção, não parte da requisição.

Fazendo isso do navegador

O painel faz exatamente os três passos acima a partir do código no cliente. A URL pré-assinada é de vida curta e delimitada a um objeto, um content type e um tamanho, então entregá-la ao navegador não dá nada reutilizável.

const signed = await fetch("/api/v1/account/avatar/upload-url", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ content_type: file.type, size_bytes: file.size }),
}).then((r) => r.json());

await fetch(signed.upload_url, {
  method: "PUT",
  headers: signed.headers,
  body: file,
});

await fetch("/api/v1/account", {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ avatar_url: signed.public_url }),
});

No painel isso passa pelo proxy /api/* do app Next, que anexa o token de sessão a partir do cookie httpOnly. O PUT vai direto para o bucket e não carrega credencial nenhuma nossa.

Comece por aqui

Conceitos

Autenticação de contatos

Guias

O fluxo

O logo da organização

O que é permitido

Substituindo uma imagem

Fazendo isso do navegador

​O fluxo

​O logo da organização

​O que é permitido

​Substituindo uma imagem

​Fazendo isso do navegador

O fluxo

O logo da organização

O que é permitido

Substituindo uma imagem

Fazendo isso do navegador