Journal d'audit

Le journal d'audit consigne, de façon immuable et horodatée, chaque action significative de votre espace de travail : connexions, transferts créés ou téléchargés, invitations de membres, changements de rôle, exports, accès aux coffres, appels d'API. Vous l'interrogez avec GET /v1/audit et vous en générez une copie complète, prête pour la conformité, avec POST /v1/audit/export. Toutes les données restent hébergées en Union européenne. Cette page décrit comment lister les entrées, filtrer, paginer, comprendre la structure d'une entrée, puis exporter.

Toutes les requêtes ciblent la base https://api.coffrify.com/v1 et s'authentifient avec l'en-tête Authorization: Bearer <clé>. Le journal est automatiquement restreint à l'espace de travail de la clé : vous ne voyez jamais les entrées d'un autre espace.

Les paramètres de requête suivants sont disponibles. Tous sont facultatifs : sans filtre, vous obtenez les entrées les plus récentes.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const { entries } = await coffrify.audit.list({
  action: 'transfer.downloaded',
  since: '2026-06-01T00:00:00Z',
  limit: 50,
});
 
for (const e of entries) {
  console.log(e.created_at, e.action, e.actor_label, e.status);
}

Structure d'une entrée

Chaque entrée décrit qui a fait quoi, sur quelle ressource, depuis où, avec quel résultat. Le champ metadata est un objet libre dont le contenu dépend de l'action (par exemple le nom d'un transfert, l'ancien et le nouveau rôle d'un membre).

Pagination par curseur

La réponse est une liste paginée par curseur : object vaut "list", data contient les entrées, has_more indique s'il reste des pages et next_cursor fournit le jeton à passer en cursor pour la suite. La pagination par curseur reste stable même lorsque de nouvelles entrées sont écrites entre deux appels, contrairement à un simple décalage.

{
  "object": "list",
  "data": [
    {
      "id": "aud_3kP9x2",
      "actor_type": "user",
      "actor_id": "mem_4Qa7",
      "actor_label": "camille@exemple.fr",
      "action": "transfer.downloaded",
      "resource_type": "transfer",
      "resource_id": "trf_8Hd2",
      "status": "success",
      "ip_address": "185.12.34.56",
      "country_code": "FR",
      "metadata": { "filename": "contrat.pdf" },
      "created_at": "2026-06-09T14:21:08Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0cyI6Ij...",
  "limit": 50
}

Pour parcourir l'intégralité du journal sans gérer le curseur à la main, le SDK fournit un itérateur asynchrone auto-paginé iterate. Il accepte aussi des durées relatives comme since: '7d'.

// Parcourt toutes les pages, des 7 derniers jours, et alerte sur les refus.
for await (const e of coffrify.audit.iterate({ since: '7d' })) {
  if (e.status === 'denied') {
    console.warn('Accès refusé:', e.action, 'par', e.actor_label);
  }
}

Cas d'usage : conformité et sécurité

Côté sécurité, filtrez sur les actions sensibles pour détecter les comportements anormaux : suivez member.role_changed et member.removed pour les changements de privilèges, surveillez les entrées dont le status vaut denied pour repérer les tentatives d'accès non autorisées, ou isolez un acteur suspect avec actor_id. Pour la traçabilité d'un dossier, filtrez par resource_type afin de reconstituer l'historique complet d'un transfert ou d'un coffre.

Côté conformité, le journal sert de preuve : combiné à l'export, il documente qui a accédé à quelles données et quand, ce qui répond aux exigences de redevabilité du RGPD et aux contrôles d'audit. Vous pouvez recevoir certains de ces évènements en temps réel via les webhooks (par exemple audit.exported).

Exporter le journal

L'export produit un fichier de qualité conformité, hébergé en France, et renvoie une URL de téléchargement temporaire. Le corps de la requête accepte format (json par défaut, ou csv), ainsi que les bornes facultatives since et until. C'est une opération lourde : réservez-la aux exports périodiques plutôt qu'aux appels à haute fréquence.

const export_ = await coffrify.audit.export({
  format: 'csv',
  since: '2026-01-01T00:00:00Z',
  until: '2026-06-30T23:59:59Z',
});
 
console.log(export_.row_count, 'entrées');
console.log('Télécharger avant', export_.expires_at);
console.log(export_.download_url);

{
  "object": "audit_export",
  "format": "csv",
  "row_count": 12840,
  "filename": "coffrify-audit-ws_7Hq2-2026-06-10.csv",
  "download_url": "https://coffrify-transfer.s3.fr-par.scw.cloud/_exports/...",
  "expires_at": "2026-06-11T09:02:44Z",
  "range": { "since": "2026-01-01T00:00:00Z", "until": "2026-06-30T23:59:59Z" }
}