Consulter l'activité d'une clé API

Réponse exemple

{
  "key": {
    "id": "key_8f3a1c9e2b7d4f60",
    "name": "Intégration comptabilité",
    "scopes": [
      "transfers:read",
      "documents:read"
    ],
    "is_active": true,
    "key_prefix": "cof_live_8f3a",
    "environment": "live",
    "last_used_at": "2026-06-05T09:42:17.000Z",
    "lifetime_used_count": 18432
  },
  "since": "2026-05-06T11:00:00.000Z",
  "range_days": 30,
  "top_routes": [
    {
      "count": 612,
      "route": "/api/v1/transfers"
    },
    {
      "count": 388,
      "route": "/api/v1/documents"
    },
    {
      "count": 14,
      "route": "/api/v1/api-keys/key_8f3a1c9e2b7d4f60/activity"
    }
  ],
  "total_calls": 1284,
  "recent_calls": [
    {
      "id": "log_3d92f0a1c5e8",
      "route": "/api/v1/transfers",
      "action": "api.get.transfers",
      "created_at": "2026-06-05T09:42:17.000Z",
      "ip_address": "203.0.113.42",
      "latency_ms": 84,
      "user_agent": "coffrify-node/2.1.0",
      "http_method": "GET",
      "http_status": 200,
      "country_code": "FR"
    },
    {
      "id": "log_7b14e9c0a2f3",
      "route": "/api/v1/documents",
      "action": "api.post.documents",
      "created_at": "2026-06-05T09:38:02.000Z",
      "ip_address": "203.0.113.42",
      "latency_ms": 31,
      "user_agent": "coffrify-node/2.1.0",
      "http_method": "POST",
      "http_status": 422,
      "country_code": "FR"
    }
  ],
  "histogram_by_day": [
    {
      "day": "2026-05-06",
      "count": 41,
      "success": 39,
      "client_errors": 2,
      "server_errors": 0
    },
    {
      "day": "2026-05-07",
      "count": 53,
      "success": 53,
      "client_errors": 0,
      "server_errors": 0
    },
    {
      "day": "2026-06-05",
      "count": 22,
      "success": 21,
      "client_errors": 1,
      "server_errors": 0
    }
  ]
}

Cet endpoint renvoie un tableau de bord d'observabilité pour une clé API donnée de votre workspace. Il agrège les entrées du journal d'audit attribuées à cette clé sur une fenêtre glissante (30 jours par défaut) et produit trois vues complémentaires : un histogramme journalier (volume, succès, erreurs client, erreurs serveur), le classement des routes les plus appelées, et la liste des derniers appels bruts. La fenêtre est plafonnée à 90 jours et les statistiques s'appuient sur au plus 500 entrées de journal les plus récentes ; au-delà, l'histogramme et les compteurs ne portent que sur ce plafond. C'est l'outil de référence pour diagnostiquer une clé suspecte, mesurer son volume ou repérer une montée d'erreurs.

Authentification

Requiert une clé API valide du workspace portant le scope api_keys:manage. Ce scope est sensible car il donne accès aux métadonnées et à l'usage de toutes les clés du workspace : réservez-le aux intégrations d'administration. La clé interrogée (paramètre id dans l'URL) doit appartenir au même workspace que la clé d'appel, sinon une erreur not_found est retournée.

Paramètres d'URL

Paramètres de requête

Réponse

Réponse 200 contenant : key (résumé de la clé : id, name, key_prefix, environment, scopes, is_active, last_used_at et lifetime_used_count qui correspond au compteur d'usage cumulé de la clé) ; range_days (la fenêtre effective appliquée) ; since (horodatage ISO 8601 du début de la fenêtre) ; total_calls (nombre d'appels analysés, plafonné à 500) ; histogram_by_day (tableau trié par jour croissant, chaque entrée portant day, count, success, client_errors, server_errors) ; top_routes (jusqu'à 10 routes triées par volume décroissant) ; et recent_calls (jusqu'à 50 appels les plus récents avec action, ip_address, country_code, user_agent, http_method, route, http_status, latency_ms, created_at).

Erreurs

Voir aussi

• GET /v1/api-keys — lister les clés API du workspace.
• GET /v1/api-keys/{id} — détail d'une clé API.
• POST /v1/api-keys — émettre une nouvelle clé API.