O que é uma URL assinada (pre-signed URL) e quando usar

Imagine que você guarda notas fiscais, contratos ou fotos de usuários em um storage privado. Ninguém de fora deve abrir esses arquivos, mas de vez em quando um usuário precisa baixar o dele. Você não quer criar uma conta para ele no storage nem fazer o arquivo passar pelo seu servidor.

A URL assinada resolve esse problema: ela entrega um link que funciona por pouco tempo e só para aquele arquivo. Em inglês, o nome é presigned URL (também pre-signed URL ou signed URL). O Amazon S3 e o Google Cloud Storage oferecem URLs assinadas, e o Azure Blob Storage tem um equivalente, a shared access signature (SAS).

Como uma URL assinada funciona?#

Uma URL assinada é uma URL comum com parâmetros extras na query string. Esses parâmetros indicam o arquivo, o método HTTP (GET para baixar, PUT para enviar) e até quando o link vale. O último parâmetro é a assinatura: um hash calculado com uma chave secreta que só o dono do storage conhece.

Quando alguém abre o link, o storage refaz o cálculo com os mesmos dados. Se a assinatura confere e o prazo não venceu, ele entrega o arquivo. Se alguém trocar o nome do arquivo ou esticar o prazo na URL, a assinatura deixa de conferir e o pedido é recusado.

Dois detalhes importam na prática:

• A URL carrega a autoridade de quem a gerou. No Amazon S3, a URL usa as credenciais do usuário que a assinou. Quem recebe o link não precisa de credenciais nem de permissões.
• Assinar não exige chamada ao storage. Seu backend assina localmente, sem acessar a rede. Só quem abre o link fala com o storage.

Para que serve uma URL assinada?#

• Download de arquivo privado: o usuário autenticado clica em "baixar fatura" e recebe um link que vale por alguns minutos.
• Upload direto do navegador: o app gera uma URL de PUT e o navegador envia o arquivo ao storage. O arquivo não passa pelo seu servidor, o que poupa banda e memória.
• Envio de arquivo para terceiros: um parceiro precisa receber um relatório uma vez, sem conta e sem senha.
• Mídia protegida: imagens ou vídeos que só usuários pagantes veem.

Como gerar uma URL assinada em Python?#

O exemplo usa o boto3, o SDK da AWS para Python, que também funciona com storages compatíveis com S3. Instale com pip install boto3 requests. As credenciais ficam em variáveis de ambiente, nunca no código.

import os

import boto3
import requests
from botocore.config import Config

s3 = boto3.client(
    "s3",
    region_name=os.environ.get("S3_REGION", "us-east-1"),
    endpoint_url=os.environ.get("S3_ENDPOINT"),  # omita no AWS S3; defina em outro storage compatível com S3
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],
    config=Config(signature_version="s3v4"),
)

download_url = s3.generate_presigned_url(  # download, vale 10 minutos
    ClientMethod="get_object",
    Params={"Bucket": "meu-bucket", "Key": "faturas/2026-10.pdf"},
    ExpiresIn=600,
)

upload_url = s3.generate_presigned_url(  # upload, vale 5 minutos
    ClientMethod="put_object",
    Params={"Bucket": "meu-bucket", "Key": "uploads/foto.jpg"},
    ExpiresIn=300,
)

print(requests.get(download_url).status_code)  # 200
with open("foto.jpg", "rb") as f:
    print(requests.put(upload_url, data=f).status_code)  # 200

Se ExpiresIn for omitido, o boto3 usa 3600 segundos (1 hora). O método HTTP do pedido precisa ser o mesmo para o qual a URL foi gerada: uma URL de GET não serve para PUT.

Para testar sem Python, copie a download_url e rode curl -o fatura.pdf "<url>". As aspas são obrigatórias, porque a URL tem vários &.

Quanto tempo uma URL assinada dura e dá para revogar?#

O prazo é você quem define, dentro do limite do storage. No Amazon S3, a documentação oficial dá estes números: até 12 horas se o link for criado no console, e até 7 dias com SDK ou CLI usando credenciais de usuário IAM. Com credenciais temporárias, como as de uma role, a URL expira junto com elas, mesmo que você tenha pedido mais tempo. Os 7 dias valem para a assinatura SigV4; outros storages têm tetos próprios (o Google Cloud Storage também aceita no máximo 7 dias).

Revogar é o ponto fraco. A URL não fica registrada em lugar nenhum: ela vale por causa da assinatura, e não existe um botão para cancelar um link específico. Os caminhos reais são desativar ou apagar a credencial usada na assinatura (o que derruba todas as URLs geradas com ela), apagar ou mover o arquivo, ou usar um mecanismo de link revogável em vez de URL assinada.

Por isso, a regra prática é gerar URLs de vida curta na hora em que o usuário pede e nunca guardar a URL pronta no banco de dados.

Quais cuidados de segurança tomar?#

• Trate a URL como senha. Quem a tiver acessa o arquivo. Evite colocá-la em logs, em analytics ou em mensagens públicas.
• Use prazos curtos. Minutos para download na tela, um pouco mais para upload de arquivos grandes.
• Limite a permissão de quem assina. Uma URL só consegue o que a credencial que a assinou consegue. Use uma credencial restrita ao bucket necessário.
• Valide o upload depois. Uma URL de PUT aceita o que for enviado. Confira tamanho e tipo do arquivo no seu backend depois do envio, ou use um POST pré-assinado (generate_presigned_post), que aceita condições de tamanho e de tipo de conteúdo.
• Mantenha o relógio em dia. Um relógio fora de sincronia pode invalidar a assinatura e gerar erros como SignatureDoesNotMatch no S3. Sincronize o servidor com NTP.

URL assinada ou link de compartilhamento: qual usar?#

Se o link é usado em segundos ou minutos, a URL assinada é a escolha certa. Se você vai passar o link a várias pessoas por dias e talvez precise cancelá-lo, use um mecanismo revogável. Para decidir o que deixar público ou privado, veja arquivo público ou privado. Para entender onde o boto3 se encaixa, leia o que é S3 e armazenamento compatível com S3 e, para arquivos grandes, upload multipart e retomável.

Como fazer isso na Square Cloud#

No Blob Storage da Square Cloud, o cenário do início (notas fiscais e contratos que só o dono baixa) fica no bucket private, e o código Python deste artigo roda nele com três trocas: o endpoint https://s3-blob.squarecloud.app, a região auto e as chaves S3 que você gera a partir de uma API key, na aba "Acesso S3" do painel. As URLs pré-assinadas SigV4 valem por até 7 dias e servem para download (GET) e para upload direto do navegador (PUT): o CORS aceita PUT de qualquer origem, desde que a API key tenha permissão de escrita.

Quando o link sai do painel, e não do seu código, a escolha é a mesma da tabela acima. O link temporário vale por até 24 horas e não pode ser revogado. O link de compartilhamento vale por até 30 dias e pode ser revogado a qualquer momento; senha e metadados no link ficam nos planos Pro e Enterprise.

O Blob não cobra taxa de saída nem de entrada, e a cota incluída vai de 5 GB a 250 GB, conforme o plano. Para testar, gere as chaves S3 no painel, defina S3_ENDPOINT e S3_REGION=auto e rode o exemplo contra o bucket private. Conheça o Blob Storage e veja a cota de cada plano em Preços.