Score de santé du workspace

Renvoie un score composite de 0 à 100 avec un détail par dimension de sécurité et des actions recommandées pour le workspace authentifié.

2 min de lectureTélécharger en PDF

Réponse exemple

{
  "plan": "business",
  "grade": "B",
  "score": 75,
  "breakdown": {
    "mfa": {
      "max": 20,
      "hint": "MFA enabled on owner ✅",
      "score": 20
    },
    "scan": {
      "max": 20,
      "hint": "2 flagged transfers - investigate",
      "score": 5
    },
    "audit": {
      "max": 20,
      "hint": "No denied/failed actions last 24h ✅",
      "score": 20
    },
    "members": {
      "max": 20,
      "hint": "Multi-person ownership ✅",
      "score": 20
    },
    "webhooks": {
      "max": 20,
      "hint": "Last 24h: 92% success",
      "score": 18
    }
  },
  "next_actions": [
    "Investigate failing webhooks (see coffrify_webhook_health_metrics)",
    "Review flagged transfers"
  ],
  "workspace_id": "ws_7f3a9c2e0b1d",
  "workspace_name": "Cabinet Durand & Associés"
}

GET/v1/workspace/healthScore de santé composite (0-100) du workspace avec détail par dimension et actions recommandées.

Calcule un score de santé composite de 0 à 100 pour le workspace authentifié, agrégeant cinq sous-scores de sécurité et de fiabilité notés chacun sur 20 : MFA du propriétaire, redondance humaine (membres actifs), fiabilité des webhooks, hygiène des transferts (scan antivirus) et activité d'audit. Chaque appel recalcule le score à la volée à partir de l'état courant du workspace : l'endpoint est en lecture seule et ne stocke ni ne met en cache de résultat. Le score est accompagné d'une note de A à F et d'une liste d'actions prioritaires (next_actions) générée dynamiquement selon les points faibles détectés.

Notez deux comportements particuliers du calcul. Le sous-score webhooks vaut un neutre 10/20 lorsqu'aucun webhook actif n'existe (l'absence de webhook n'est pas pénalisée comme un échec) ; lorsqu'au moins un webhook est actif, il reflète le taux de succès des livraisons des dernières 24 heures. Le sous-score scan observe les transferts marqués infected, quarantined ou flagged sur une fenêtre de 30 jours, tandis que les sous-scores audit et webhooks portent sur les 24 dernières heures.

Authentification

Requiert une clé API valide, aucun scope spécifique : l'endpoint est gratuit pour toute clé du workspace et ne déclare pas de requiredScope. L'accès est strictement limité au workspace de la clé (ctx.workspaceId) ; il n'est pas possible d'interroger la santé d'un autre workspace. Transmettez la clé via l'en-tête Authorization: Bearer cof_live_....

Paramètres de requête

Cet endpoint n'accepte aucun paramètre de requête ni corps. Le workspace ciblé est entièrement déterminé par la clé API. La méthode OPTIONS est gérée pour le préflight CORS.

Réponse

Renvoie 200 avec un objet JSON. Les champs racine identifient le workspace et donnent le verdict global ; l'objet breakdown détaille chaque dimension.

Champ	Type	Description
workspace_id	string	Identifiant du workspace authentifié.
workspace_name	string \| null	Nom du workspace, ou `null` si introuvable.
plan	string	Plan du workspace en minuscules (ex. `free`, `business`) ; `free` par défaut.
score	number	Score composite total sur 100 (somme des cinq sous-scores sur 20).
grade	string	Note : `A` (≥90), `B` (≥75), `C` (≥60), `D` (≥40), sinon `F`.
breakdown.mfa	object	Sous-score MFA `{ score, max: 20, hint }` : 20 si MFA activé sur le propriétaire, sinon 0.
breakdown.members	object	Sous-score redondance : 20 si ≥2 membres actifs, 10 si 1, sinon 0.
breakdown.webhooks	object	Sous-score webhooks : taux de succès des livraisons sur 24h × 20 ; 10 (neutre) si aucun webhook actif.
breakdown.scan	object	Sous-score scan : 20 si aucun transfert signalé sur 30 jours, sinon 5.
breakdown.audit	object	Sous-score audit : 20 si ≤2 actions refusées/échouées sur 24h, 10 si ≤10, sinon 0.
next_actions	string[]	Liste filtrée d'actions prioritaires recommandées (vide si tout est au vert).

Erreurs

Code	Quand	Résolution
missing_api_key	401 — aucun en-tête `Authorization` fourni.	Ajoutez `Authorization: Bearer cof_live_...` à la requête.
invalid_api_key	401 — clé inconnue ou malformée.	Vérifiez la clé dans la console developer et régénérez-la si besoin.
expired_api_key	401 — clé expirée.	Émettez une nouvelle clé API.
revoked_api_key	401 — clé révoquée.	Utilisez une clé active non révoquée.
ip_not_allowed	403 — IP appelante hors de la liste autorisée de la clé.	Appelez depuis une IP autorisée ou ajustez l'allowlist de la clé.
rate_limited	429 — quota par minute du workspace dépassé (endpoint classé `read`).	Respectez l'en-tête `Retry-After` et réduisez la cadence d'appels.
internal_error	500 — erreur inattendue côté serveur.	Réessayez ; si le problème persiste, contactez le support avec le `request_id`.

Voir aussi

GET /v1/webhooks — lister les webhooks dont la fiabilité alimente le sous-score webhooks.
GET /v1/audit-log — consulter les actions refusées/échouées prises en compte dans le sous-score audit.
GET /v1/transfers — inspecter les transferts dont le statut de scan pèse sur le sous-score scan.