Le Coffre chiffré

Le Coffre est l'espace de stockage persistant de Coffrify, à l'opposé du transfert, qui est éphémère et expire. Là où un transfert sert à envoyer quelques fichiers via un lien à durée de vie limitée, un coffre conserve durablement un ensemble de documents au même endroit : une data room pour une opération de fusion-acquisition, un espace client qui vit pendant toute la durée d'une mission, ou une bibliothèque de référence partagée avec des invités. Cette page explique comment créer et piloter un coffre via l'API REST https://api.coffrify.com/v1, comment y organiser des éléments et des fichiers, comment gérer les invités, et comment en produire un export vérifiable. Toutes les requêtes s'authentifient avec l'en-tête Authorization: Bearer <clé>.

Transfert ou coffre : lequel choisir ?

Un transfert est conçu pour une remise ponctuelle : il porte une date d'expiration, un nombre maximal de téléchargements, et disparaît une fois sa mission accomplie. Un coffre, lui, est fait pour durer. On y dépose des éléments qui restent accessibles tant que vous ne les retirez pas, on les range en sections et en dossiers, on l'ouvre à des invités nommés, et on en suit les accès. Si vous hésitez, la règle est simple : pour envoyer, prenez un transfert ; pour conserver et donner accès dans le temps, prenez un coffre.

Chiffrement : standard ou bout en bout

Par défaut, le contenu d'un coffre est chiffré côté serveur en AES-256-GCM, et l'hébergement reste en Union européenne. C'est le mode recommandé pour la plupart des usages : vos documents sont chiffrés au repos, et vous gardez les fonctions pratiques comme le partage public et la gestion des invités.

Un mode chiffrement de bout en bout (zero-knowledge) est proposé en option. Dans ce mode, la clé reste chez vous et le serveur ne peut pas lire le contenu. C'est ce mode qui est requis pour déposer des fichiers persistants dans un coffre (les sous-ressources /files et /folders décrites plus bas). Le compromis est important et doit être accepté en connaissance de cause.

Créer un coffre

Seul le champ title est obligatoire. Si vous ne fournissez pas de slug, il est généré à partir du titre et rendu unique dans votre espace de travail. Le slug est ce qui apparaît dans l'URL publique du coffre, de la forme /c/<slug>. Pensez à passer l'en-tête Idempotency-Key sur cette écriture pour pouvoir réessayer sans risque de doublon.

curl -X POST https://api.coffrify.com/v1/coffres \
  -H "Authorization: Bearer cof_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: coffre-acme-dataroom-001" \
  -d '{
    "title": "Data room ACME",
    "description": "Documents de due diligence",
    "status": "active",
    "password": "un-secret-fort",
    "watermark_enabled": true,
    "require_nda": true,
    "allowed_emails": ["conseil@acquereur.fr"]
  }'

La réponse renvoie le coffre créé, avec son id, son slug, son status et les compteurs de consultation. Un coffre nouvellement créé est en statut draft par défaut ; passez status à active pour le rendre consultable, ou plus tard via une mise à jour.

Champs du coffre

Voici les champs que vous pouvez fournir à la création (POST) et, pour la plupart, modifier ensuite (PATCH).

Lire, modifier et supprimer un coffre

Le GET détaillé renvoie le coffre, son tableau sections (chaque section portant ses propres items) et un tableau orphan_items pour les éléments non rattachés à une section. Pour lister tous vos coffres, appelez GET /v1/coffres, qui renvoie un objet de type list. Le PATCH n'accepte que les champs modifiables (titre, description, statut, paramètres d'accès, couverture). Par exemple, pour activer un coffre resté en brouillon :

curl -X PATCH https://api.coffrify.com/v1/coffres/cof_id_123 \
  -H "Authorization: Bearer cof_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

Organiser le contenu : éléments et sections

Le contenu d'un coffre s'organise en éléments (items), eux-mêmes regroupables en sections. Un élément peut être de trois natures : un transfert existant de votre espace de travail (kind: "transfer"), un lien externe (kind: "external_url"), ou une note en Markdown (kind: "markdown"). Cela permet d'assembler une page de coffre mêlant documents, ressources externes et explications.

Selon la nature, le corps attend un champ différent : transfer_id pour un transfert (qui doit appartenir au même espace de travail), external_url pour un lien, ou markdown_content pour une note. Vous pouvez aussi fournir custom_title, custom_description et section_id.

curl -X POST https://api.coffrify.com/v1/coffres/cof_id_123/items \
  -H "Authorization: Bearer cof_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "transfer",
    "transfer_id": "trf_id_789",
    "custom_title": "Comptes consolidés 2025"
  }'

Les méthodes GET, PATCH et DELETE de /v1/coffres/{id}/items complètent le cycle. Pour modifier ou retirer un élément, passez son identifiant dans le corps via le champ item_id. Lister les éléments renvoie un objet de type list, trié par section puis par position.

Fichiers persistants et dossiers (mode bout en bout)

Au-delà des éléments, un coffre peut héberger de vrais fichiers persistants, organisés en arborescence de dossiers, à la manière d'un espace de stockage chiffré. Cette fonction s'appuie sur le chiffrement de bout en bout : elle requiert donc que le mode soit activé sur le coffre au préalable. Tant qu'il ne l'est pas, ces endpoints répondent par une erreur 409 vous invitant à l'activer.

• GET /v1/coffres/{id}/files : liste les fichiers persistants (filtre optionnel ?folder_id=<uuid> ou ?folder_id=root).
• POST /v1/coffres/{id}/files/upload-url : obtient une URL d'envoi pour déposer un fichier.
• POST /v1/coffres/{id}/files/commit : confirme le dépôt une fois l'envoi terminé.
• GET /v1/coffres/{id}/files/{fileId}/download-url : obtient une URL de téléchargement à durée limitée.
• GET et POST /v1/coffres/{id}/folders : liste et crée des dossiers (la création d'un sous-dossier accepte parent_id).

Parce que le contenu est chiffré de bout en bout, le serveur ne voit jamais le clair : la clé reste chez vous, c'est votre application qui chiffre avant l'envoi et déchiffre après le téléchargement. En pratique, le SDK JavaScript/Node gère ce cycle pour vous. Le SDK officiel n'existe aujourd'hui que pour JavaScript et Node.js. Pour Python, Go, Ruby, PHP, Rust, Java ou .NET, un SDK est bientôt disponible ; en attendant, l'API REST reste utilisable directement (curl, fetch).

Inviter des personnes : les invités

Un coffre peut être ouvert à des invités nommés par leur adresse e-mail, sans qu'ils aient besoin de créer un compte. Chaque invitation génère un lien d'accès personnel. La gestion des invités utilise un scope dédié, coffres:manage, distinct du scope d'écriture du coffre : n'accordez ce scope qu'aux clés qui en ont réellement besoin.

Le corps attend email ; vous pouvez préciser can_download (autorisé par défaut), une note interne et une date expires_at. Les méthodes GET (lister), PATCH (modifier les droits, via guest_id) et DELETE (révoquer, via guest_id) complètent la gestion. La réponse à une invitation inclut le lien d'accès personnel à transmettre.

curl -X POST https://api.coffrify.com/v1/coffres/cof_id_123/guests \
  -H "Authorization: Bearer cof_rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "avocat@cabinet.fr",
    "can_download": true,
    "note": "Conseil de l'acquéreur"
  }'

Exporter un coffre

L'export renvoie un document JSON auto-portant qui rassemble le coffre, ses sections, ses éléments et la chaîne de preuve associée, le tout attesté par une empreinte signée. Il sert à la réversibilité et à l'archivage : vous pouvez le conserver hors de Coffrify et en vérifier l'intégrité plus tard. La réponse indique notamment chain_valid, chain_length et un bloc attestation (empreinte, référence, horodatage).

$ curl https://api.coffrify.com/v1/coffres/cof_id_123/export \
    -H "Authorization: Bearer cof_live_..." | jq '.chain_valid, .attestation.reference'
true
"Z42-EXPORT-cof_id_123"

Idempotence, limites de débit et erreurs

Toutes les écritures (création, mise à jour, ajout d'éléments, invitations) acceptent un en-tête Idempotency-Key de 8 à 255 caractères. Un rejeu avec la même clé renvoie la réponse mémorisée, accompagnée de l'en-tête X-Coffrify-Idempotent-Replay: true ; la même clé avec un corps différent renvoie un code 409. Les réponses portent les en-têtes de quota X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset et X-RateLimit-Policy, et un Retry-After en cas de 429.

Les erreurs suivent une enveloppe homogène, avec un request_id à citer en cas de demande de support :

{
  "error": {
    "code": "scope_missing",
    "message": "This API key is missing the required scope.",
    "request_id": "req_..."
  }
}

Pour vos tests, utilisez une clé cof_test_…, ou une clé cof_sandbox_… pour un environnement bac à sable isolé et éphémère (24 h, hors facturation), avec des garde-fous adaptés. Passez en cof_live_… une fois votre intégration validée, et restreignez chaque clé aux seuls scopes nécessaires (transfers:read, transfers:write, coffres:manage).