Générer une URL de téléchargement signée et éphémère

L'endpoint POST /v1/transfers/{id}/download-url génère une ou plusieurs URL S3 pré-signées (AWS4-HMAC-SHA256) pointant directement vers les fichiers stockés dans l'espace Scaleway Object Storage de Coffrify. Ces URLs sont éphémères : leur durée de vie est strictement bornée entre 60 secondes et 24 heures. Elles court-circuitent la porte de partage public (mot de passe, lien expirable) et n'incrémentent pas le compteur total_downloads du transfert. Cet endpoint est réservé aux usages opérationnels côté serveur : agents, pipelines d'archivage, intégrations MCP ou scripts de sauvegarde.

Authentification

Les deux endpoints exigent une clé API transmise dans l'en-tête Authorization: Bearer <clé>. Le format accepté est cof_live_… (production) ou cof_test_… (sandbox). Le scope transfers:download est requis pour POST /download-url ; le scope downloads:read est requis pour GET /downloads. Toute requête avec une clé invalide, révoquée ou dépourvue du scope adéquat retourne une erreur 401 ou 403.

Corps de la requête

Le corps précise le fichier visé (ou tous) et la durée de validité souhaitée. Le tableau ci-dessous détaille les champs acceptés.

Exemples de code

L'exemple ci-dessous génère une URL pré-signée puis l'utilise immédiatement pour télécharger le fichier. À exécuter côté serveur uniquement. Choisissez votre langage.

# Générer une URL valable 10 minutes pour un fichier précis
curl -X POST https://api.coffrify.com/v1/transfers/trf_01HXYZ123/download-url \
  -H "Authorization: Bearer cof_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "f8a2c3d4-1234-5678-abcd-ef0123456789",
    "expires_in_seconds": 600
  }'

Réponse

La réponse renvoie l'URL signée, sa durée de validité (expires_in_seconds) et son échéance (expires_at). Au-delà, l'URL devient inutilisable : régénérez-en une au besoin.

{
  "transfer_id": "trf_01HXYZ123",
  "short_code": "abc123",
  "expires_in_seconds": 600,
  "expires_at": "2026-06-06T12:10:00.000Z",
  "files": [
    {
      "file_id": "f8a2c3d4-1234-5678-abcd-ef0123456789",
      "file_name": "rapport-annuel-2025.pdf",
      "file_size": 2048576,
      "file_type": "application/pdf",
      "download_url": "https://coffrify-transfer.s3.fr-par.scw.cloud/trf_01HXYZ123/rapport-annuel-2025.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Expires=600&X-Amz-Signature=..."
    }
  ],
  "note": "These URLs bypass the public share + password gate AND do NOT increment total_downloads. For admin/agent operational use only."
}

Erreurs

Les erreurs portent sur le transfert introuvable, le scope manquant (transfers:download) ou un fichier inexistant. Le tableau ci-dessous indique la résolution.

• Créer un transfert
• Lister les fichiers d'un transfert
• Étendre l'expiration d'un transfert
• Authentification et scopes API
• Limites de débit et quotas