ResponZDocs

Accès API

Une clé d'API permet à un script ou à un outil de lire vos données ResponZ sans navigateur. Une clé est en lecture seule, appartient à votre organisation et se révoque à tout moment.

Créer une clé

Les clés se gèrent dans Réglages › Organisation › Accès API. Seul le propriétaire de l'organisation peut créer ou révoquer une clé ; les autres membres voient la liste.

  1. Cliquez sur Créer une clé et donnez-lui un nom qui dit où elle va servir, par exemple « Export nocturne ».
  2. Choisissez les permissions et la durée de validité.
  3. Cliquez sur Créer. La clé complète s'affiche une seule fois. Copiez-la avant de fermer la fenêtre : elle ne pourra plus être affichée, et une clé perdue se remplace par une nouvelle.

Une organisation peut avoir jusqu'à 10 clés actives. La liste montre pour chaque clé son préfixe (rz_live_1a4b…), ses permissions, sa date de création, sa dernière utilisation et son échéance. Une clé jamais utilisée porte la pastille Jamais utilisée : en général, la clé n'a pas été collée dans l'outil.

Attention

Les données lues par une clé partent vers l'outil auquel vous la connectez. Traitez la clé comme un mot de passe : rangez-la dans le coffre à secrets de votre outil, jamais dans du code source.

Utiliser la clé

Envoyez la clé dans l'en-tête Authorization, après Bearer. Ni cookie ni en-tête d'organisation : la clé porte son organisation, et ne lit jamais que les données de celle-ci.

curl https://api.responz.io/v1/analytics/summary \
  -H "Authorization: Bearer rz_live_..."

Les réponses sont le JSON que lit le dashboard ResponZ lui-même. Les routes datées acceptent les paramètres from et to, et couvrent par défaut les 90 derniers jours.

Permissions

  • Statistiques et analyses (read:analytics) : toujours accordée. Chiffres, tendances, regroupements de sujets, objectifs, catégories et indicateurs de documentation.
  • Contenu des conversations (read:conversations) : décochée par défaut. Inclut le texte des messages de vos clients, et tout ce qui nomme un client ou un contact. Ne la cochez que si votre outil en a besoin.

Ce qu'une clé peut lire

Une clé est en lecture seule. Elle n'accepte que des requêtes GET, sur une liste fixe de routes. Tout le reste répond une erreur, même avec une clé valide.

Avec read:analytics :

  • /v1/dashboard/overview, /v1/dashboard/trends
  • les indicateurs /v1/analytics/* (synthèse, volume, SLA, CSAT, backlog, agents, prévisions…), sauf ceux listés sous read:conversations
  • /v1/trends/series, /v1/trends/annotations
  • /v1/objectives, /v1/objectives/progress, /v1/objectives/suggestions
  • /v1/clusters, /v1/categories, /v1/categories/stats
  • les indicateurs de documentation /v1/docs/*, sauf un article seul
  • les exports CSV /v1/export/clusters et /v1/export/gaps

Avec read:conversations en plus :

  • /v1/conversations, /v1/conversations/:id, /v1/quality-scores
  • /v1/clusters/:id/conversations, /v1/clusters/:id/answers, /v1/docs/articles/:id
  • dans /v1/analytics : fin/loops, open-risk, churn-risk, accounts/:companyId/journey, surveys, top-customers, unconverted-leads, free-tier-accounts
  • les exports CSV /v1/export/conversations, /v1/export/quality-scores, /v1/export/churn

Une clé n'atteint jamais Ask AI ni la recherche (elles consomment des crédits IA), la facturation, les réglages de l'organisation et de l'équipe, le journal d'audit, ni la gestion des clés : une clé ne crée pas de clé. Votre offre s'applique comme dans le dashboard : les exports CSV commencent à l'offre Starter.

Durée de validité

À la création, choisissez 30 jours, 90 jours (par défaut), 1 an ou sans expiration. Une clé expirée cesse de fonctionner et porte la pastille Expirée le. Elle ne se prolonge pas : créez-en une nouvelle, puis révoquez l'ancienne pour la retirer de la liste.

Limite d'appels

Chaque clé peut passer 60 appels par minute. Le compteur repart à zéro au début de chaque minute et il est propre à chaque clé : deux clés d'une même organisation ne le partagent pas. Au-delà, l'API répond 429 avec un en-tête Retry-After qui donne le nombre de secondes à attendre.

Réponses d'erreur

  • 401 Invalid API key : clé inconnue, mal formée, expirée ou révoquée, ou clé dont le créateur a quitté l'organisation.
  • 401 Unauthorized : une route qu'une clé ne peut pas atteindre.
  • 403 API_KEY_SCOPE : la route exige read:conversations et la clé ne l'a pas.
  • 403 API_KEY_READ_ONLY : toute méthode autre que GET.
  • 402 : la fonction n'est pas incluse dans votre offre.
  • 429 : limite d'appels atteinte, voir Retry-After.

Révoquer une clé

Dans Réglages › Organisation › Accès API, le propriétaire clique sur Révoquer et confirme. La clé cesse de fonctionner dès l'appel suivant ; la révocation est irréversible. La clé quitte la liste mais reste au journal d'audit.

Le journal d'audit a un onglet Accès API : il garde la création, la première utilisation et la révocation de chaque clé. Voir Sécurité & données.