Cette page rassemble les termes que vous croiserez dans la documentation, le tableau de bord et les réponses de l'API Coffrify. Les définitions sont volontairement orientées usage : ce que le mot désigne et comment vous vous en servez quand vous appelez https://api.coffrify.com/v1. Gardez-la sous la main, elle sert de référence rapide quand un champ ou un en-tête vous semble obscur.
Objets principaux
Transfert : un envoi de fichiers que vous créez avec POST /v1/transfers. Vous décrivez les fichiers (name, size, mime_type), l'API renvoie un objet transfer (avec un id, un short_code, un status, une share_url et une date expires_at) ainsi que des upload_urls. Vous téléversez chaque fichier en PUT vers l'URL fournie, puis vous partagez la share_url. Vous pouvez fixer une expiration (expires_in_hours), un nombre maximal de téléchargements (max_downloads), un mot de passe (password) ou un destinataire (recipient).
Réception (intake) : un point de dépôt sécurisé que des tiers alimentent à votre place, l'équivalent d'une boîte de réception confidentielle. Vous le créez avec POST /v1/intakes. L'API renvoie deux clés : une clé publishable cip_, sûre à exposer dans un navigateur pour collecter des fichiers, et une clé secrète cof_ à garder côté serveur pour gérer la réception et lire les documents via /v1/intakes/{id}/documents. C'est le moyen d'inviter quelqu'un à vous envoyer des fichiers sans lui ouvrir un compte.
Coffre (data room) : un espace de stockage et de partage organisé, pensé pour rassembler des documents au même endroit et en maîtriser l'accès dans la durée. Là où un transfert est éphémère, un coffre est un dépôt structuré que vous conservez.
Authentification et permissions
**Clé API (cof_*)** : le secret que vous présentez dans l'en-tête Authorization: Bearer <clé> pour vous authentifier. Le préfixe indique l'environnement et le type. Ne l'exposez jamais côté navigateur (utilisez pour cela la clé publishable cip_ d'une réception).
| Préfixe | Type de clé |
|---|---|
| cof_live_ | Clé de production (données réelles) |
| cof_test_ | Clé de test |
| cof_sandbox_ | Clé du bac à sable (environnement isolé, 24 h) |
| cof_rk_ | Clé restreinte (scopes limités) |
| cof_mcp_ | Jeton MCP, pour les agents et assistants compatibles |
| cip_ | Clé publishable d'une réception, sûre côté navigateur |
Scope (portée) : une permission attachée à une clé qui décrit ce qu'elle a le droit de faire. Vous accordez le minimum nécessaire. Les principaux sont transfers:read et transfers:write, collections:read, collections:write et collections:manage, intake:read et intake:write, webhooks:read et webhooks:manage, api_keys:manage, et gdpr:export. Si une clé appelle un endpoint sans le scope requis, l'API répond par l'erreur scope_missing.
Fiabilité des appels
Idempotence : la garantie que rejouer la même écriture ne la déclenche qu'une fois. Sur les requêtes qui modifient des données, ajoutez un en-tête Idempotency-Key (de 8 à 255 caractères). Si vous renvoyez la même clé avec le même corps, vous récupérez la réponse d'origine, signalée par X-Coffrify-Idempotent-Replay: true, au lieu de créer un doublon. Réutiliser la même clé avec un corps différent renvoie une erreur 409.
Rate limit (limite de débit) : le plafond d'appels autorisés sur une fenêtre de temps. Chaque réponse porte les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset et X-RateLimit-Policy. Quand vous dépassez le plafond, l'API renvoie un statut 429 avec l'erreur rate_limited et un en-tête Retry-After indiquant le nombre de secondes à patienter.
Backoff (temporisation) : la stratégie consistant à attendre, puis à espacer progressivement vos tentatives après une erreur temporaire. En cas de 429, respectez d'abord la valeur de Retry-After, puis augmentez le délai entre chaque essai pour laisser le débit revenir sous le plafond.
Notifications et signature
Webhook : une notification que Coffrify envoie à votre serveur quand un évènement se produit. Vous l'enregistrez avec POST /v1/webhooks ; sans précision, il est abonné à l'évènement transfer.downloaded. À la création, vous recevez un secret de signature commençant par whsec_, à conserver pour vérifier l'authenticité des appels reçus.
Signature (de webhook) : la preuve, jointe à chaque livraison, que le message vient bien de Coffrify et n'a pas été altéré. Coffrify signe selon deux conventions en parallèle : le standard Standard Webhooks (en-têtes webhook-id, webhook-timestamp et webhook-signature) et un format historique (X-Coffrify-Signature). Recalculez la signature avec votre secret whsec_ et comparez ; une tolérance d'horodatage de 5 minutes protège contre les rejeux.
Environnements
Environnement : le contexte dans lequel vos appels s'exécutent, déterminé par le préfixe de votre clé. live agit sur vos données réelles, test sert à vos essais, et sandbox est un terrain de jeu isolé. Vous changez d'environnement en changeant simplement de clé.
Bac à sable (sandbox) : un environnement éphémère et cloisonné pour expérimenter sans risque. Les clés cof_sandbox_ expirent au bout de 24 h, les données y sont isolées, et des garde-fous s'appliquent (10 Mo par fichier, 10 fichiers, 25 transferts par 24 h, 5 téléchargements). Le bac à sable est hors facturation.
Chiffrement et accès agents
Chiffrement de bout en bout (zero-knowledge) : un mode optionnel dans lequel la clé de déchiffrement reste chez vous et le serveur ne lit pas le contenu. Par défaut, les fichiers sont chiffrés côté serveur (AES-256-GCM) ; avec le mode de bout en bout, Coffrify ne peut pas accéder aux données. Conséquence directe : si vous perdez la clé, les données sont définitivement irrécupérables, personne ne peut les restaurer à votre place.
MCP (Model Context Protocol) : le moyen de connecter un assistant ou un agent à Coffrify pour qu'il agisse en votre nom (lister des transferts, en créer, gérer des webhooks, selon ses scopes). Vous l'authentifiez avec un jeton cof_mcp_ et le serveur hébergé répond sur mcp.coffrify.com/<workspace>. Les permissions d'un jeton MCP suivent les mêmes scopes que les clés API.
Un dernier repère transversal. Erreur : en cas d'échec, l'API renvoie toujours un objet de la forme {"error":{"code","message","request_id"}}. Les codes courants sont invalid_api_key, scope_missing, validation_error, not_found et rate_limited. Le champ request_id identifie l'appel et facilite le support si vous devez nous le transmettre.