URL de téléchargement

Une URL signée de téléchargement accorde l'accès en lecture à exactement un chemin stocké, jusqu'à un instant que vous choisissez. Vous l'émettez avec une session ; elle s'utilise sans.

POST /api/buckets/documents/sign
Content-Type: application/json
Cookie: <session>

{
  "path": "9f3c1e2a-7b44-4d10-9e21-8a6f0c1d2e3b-contract.pdf",
  "expiresIn": 3600
}

{
  "success": true,
  "signedUrl": "https://app.example.com/api/buckets/documents/signed?path=9f3c1e2a-…-contract.pdf&op=download&expires=1775386800000&token=4b1f…",
  "expiresAt": "2026-04-05T11:00:00Z",
  "operation": "download"
}

operation vaut download par défaut : le champ est donc omis ci-dessus. Confiez signedUrl à un navigateur, à un gabarit de courriel ou à un moteur de rendu PDF — rien d'autre ne lui est nécessaire.

Corps de la requête

Champ	Type	Requis	Défaut	Remarques
path	chaîne	Oui	—	La clé de stockage, exactement telle que renvoyée au téléversement.
expiresIn	entier	Non	3600	Durée de vie en secondes. Entre 60 et 604800 (7 jours).
operation	chaîne	Non	download	download ou upload. Voir Téléversement.

Issues possibles

Situation	Résultat
Requête valide	200 avec signedUrl et expiresAt.
expiresIn inférieur à 60 ou supérieur à 604800	400
path absent ou vide	400
Aucun fichier à path	404 — un jeton de lecture doit viser des octets réels
Sans session	401
Session sans la permission sign du bucket	404
Bucket inconnu	404

Notez la vérification d'existence. Contrairement à la signature de téléversement, la signature de téléchargement refuse d'émettre un jeton pour un chemin vide : une URL signée que vous détenez est donc une URL qui s'est résolue au moins une fois.

Utiliser l'URL et la voir expirer

L'URL se résout sur GET /api/buckets/{bucket}/signed. Trois choses peuvent alors mal tourner, et les trois répondent 403 :

À l'utilisation	Résultat
Dans la fenêtre, signature intacte	200 avec les octets.
Après expiresAt	403
Tout paramètre modifié — chemin, expiration, opération	403 (signature non concordante)
Jeton de téléversement utilisé en GET	403 (opération non concordante)
Jeton valide mais fichier supprimé entre-temps	404

Les jetons sont comparés en temps constant : un jeton malformé ou proche du bon ne fuite donc rien par le temps de réponse. Le 403 d'expiration et le 403 de falsification sont délibérément la même réponse.

Transformations sur une URL signée

L'URL signée d'une image accepte des paramètres de transformation ajoutés à sa suite. Le jeton couvre path, op et expires — pas la requête de transformation — de sorte qu'une seule URL signée sert toutes les tailles :

<signedUrl>&width=200&fit=cover

Les images matricielles arrivent avec Content-Disposition: inline sur cette route et s'affichent donc directement dans un <img>. Pas le SVG : il est forcé en attachment, car un SVG affiché en ligne sur votre origine peut exécuter du script. Voir Sécurité des téléversements.

Pages associées

• URL signées — pourquoi la signature existe et qui peut signer.
• Téléversement et signature par lot — jetons d'écriture et émission en masse.
• Champs de pièce jointe et stockage — les enregistrements qui arrivent pré-signés.
• Redimensionnement et recadrage — les paramètres que vous pouvez ajouter.
• Opérations sur les fichiers — le téléchargement fondé sur la session.