# 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.

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

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

```json
{
  "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](/fr/docs/signed-urls-upload). |

## 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.

:::callout
**Choisissez la fenêtre la plus courte qui fonctionne.** Une URL signée ne peut pas être révoquée individuellement — une fois émise, elle est valide jusqu'à `expiresAt`, quoi qu'il advienne entre-temps de la session, du rôle ou du compte de l'utilisateur. Soixante secondes pour une redirection, une heure pour un lien de courriel, sept jours uniquement pour un usage réellement durable. La seule révocation globale consiste à faire tourner `AUTH_SECRET`, ce qui invalide toutes les URL en circulation d'un coup.
:::

## Transformations sur une URL signée

L'URL signée d'une image accepte des [paramètres de transformation](/fr/docs/image-transforms) 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 :

```text
<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](/fr/docs/file-security).

## Pages associées

- [URL signées](/fr/docs/signed-urls) — pourquoi la signature existe et qui peut signer.
- [Téléversement et signature par lot](/fr/docs/signed-urls-upload) — jetons d'écriture et émission en masse.
- [Champs de pièce jointe et stockage](/fr/docs/attachment-storage) — les enregistrements qui arrivent pré-signés.
- [Redimensionnement et recadrage](/fr/docs/image-transforms) — les paramètres que vous pouvez ajouter.
- [Opérations sur les fichiers](/fr/docs/file-operations) — le téléchargement fondé sur la session.