Auditer l'activité d'une clé API (derniers appels, IPs, scopes utilisés)

Deux endpoints vous permettent d'auditer l'activité d'une clé API. Le premier, GET /v1/api-keys/{id}/activity, est dédié à une clé précise : il renvoie un histogramme journalier des appels sur la période demandée (1 à 90 jours), les 10 routes les plus appelées et les 50 derniers appels avec IP, pays, user-agent et code HTTP. Le second, GET /v1/audit, interroge le journal transversal du workspace avec filtres sur l'acteur (actor_id), l'action, le type de ressource et une plage de dates. Ces deux endpoints sont complémentaires : le premier pour le pilotage clé par clé, le second pour la vue RGPD et conformité.

Authentification

Les deux endpoints nécessitent une clé API active transmise dans l'en-tête Authorization: Bearer <cof_live_…>. Le scope requis est api_keys:manage pour /v1/api-keys/{id}/activity et audit:read pour /v1/audit. Pour exporter le journal complet au format CSV ou JSON, l'endpoint POST /v1/audit/export demande le scope audit:export. Ces trois scopes sont classés sensibles dans le catalogue interne de Coffrify : leur attribution à une clé déclenchera une confirmation MFA (TOTP) ou un double-confirm explicite lors de la création de la clé.

Paramètres de requête

Les deux endpoints acceptent une fenêtre temporelle et, pour le journal transversal, des filtres (action, acteur, ressource). Le tableau ci-dessous les détaille par endpoint.

Exemples d'appels

Les exemples ci-dessous récupèrent l'activité d'une clé précise, puis le journal d'audit du workspace. Choisissez votre langage.

# Activité d'une clé sur 14 jours
curl -s \
  -H "Authorization: Bearer cof_live_4a7b2c..." \
  "https://api.coffrify.com/v1/api-keys/key_01hx.../activity?days=14" \
  | jq .
 
# Journal d'audit filtré sur une clé (derniers 50 appels)
curl -s \
  -H "Authorization: Bearer cof_live_4a7b2c..." \
  "https://api.coffrify.com/v1/audit?actor_id=key_01hx...&limit=50" \
  | jq .

Réponse, activité d'une clé

La réponse agrège un histogramme journalier, le top des routes appelées et les derniers appels (recent_calls). Surveillez ces derniers : une IP ou un pays inhabituel peut signaler une fuite de clé.

{
  "key": {
    "id": "key_01hx9z8y7w6v5u4t",
    "name": "Integration CI/CD",
    "key_prefix": "cof_live_4a7b2c8d...",
    "environment": "live",
    "scopes": ["transfers:read", "transfers:write"],
    "is_active": true,
    "last_used_at": "2026-06-06T08:14:32Z",
    "lifetime_used_count": 1847
  },
  "range_days": 14,
  "since": "2026-05-23T08:20:00.000Z",
  "total_calls": 312,
  "histogram_by_day": [
    { "day": "2026-05-23", "count": 18, "success": 17, "client_errors": 1, "server_errors": 0 },
    { "day": "2026-05-24", "count": 24, "success": 24, "client_errors": 0, "server_errors": 0 },
    { "day": "2026-06-06", "count": 41, "success": 39, "client_errors": 2, "server_errors": 0 }
  ],
  "top_routes": [
    { "route": "/v1/transfers", "count": 198 },
    { "route": "/v1/transfers/{id}", "count": 67 },
    { "route": "/v1/recipients", "count": 47 }
  ],
  "recent_calls": [
    {
      "id": "log_01jx...",
      "action": "transfer.created",
      "ip_address": "185.220.101.42",
      "country_code": "FR",
      "user_agent": "axios/1.6.8 Node.js/20.11.0",
      "http_method": "POST",
      "route": "/v1/transfers",
      "http_status": 201,
      "latency_ms": 143,
      "created_at": "2026-06-06T08:14:32Z"
    }
  ]
}

Réponse, journal d'audit paginé

Le journal transversal renvoie les entrées (data) et un next_cursor pour la page suivante. Chaque entrée trace l'acteur, l'action et la ressource concernée.

{
  "data": [
    {
      "id": "log_01jx...",
      "action": "transfer.created",
      "ip_address": "185.220.101.42",
      "country_code": "FR",
      "user_agent": "axios/1.6.8 Node.js/20.11.0",
      "http_method": "POST",
      "route": "/v1/transfers",
      "http_status": 201,
      "latency_ms": 143,
      "created_at": "2026-06-06T08:14:32Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0cyI6IjIwMjYtMDYtMDZUMDg6...",
  "note": "Audit retention follows the workspace plan: Free 30 days, Pro 1 year, Ultra/Entreprise 7 years."
}

Erreurs

Les erreurs portent surtout sur le scope api_keys:manage manquant ou une clé introuvable. Le tableau ci-dessous indique la résolution.

Voir aussi

• Créer et gérer vos clés API
• Révoquer et faire tourner une clé API
• Exporter le journal d'audit (CSV/JSON)
• Référence : GET /v1/api-keys/{id}/activity
• Référence : GET /v1/audit
• Référence : POST /v1/audit/export