Authentification et clés API

Pro Plan

Sécurisez votre accès API avec des clés API. Créez et gérez les clés pour vos intégrations.

Info

L'API REST Zenovay est une fonctionnalité payante. Vous avez besoin d'un plan Pro ou supérieur pour créer et utiliser des clés API. Les équipes gratuites peuvent toujours envoyer des événements avec le script de suivi, mais pas appeler l'API programmatique.

Méthodes d'authentification

Clés API (Principal)

Authentifiez-vous en utilisant l'en-tête X-API-Key (recommandé) ou l'en-tête Authorization: Bearer :

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Ou en utilisant l'authentification Bearer :

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

Les clés API commencent toujours par le préfixe zv_.

Création de clés API

Les clés API dans Zenovay sont des clés personnelles : chaque demande est attribuée à vous, l'utilisateur qui a créé la clé.

Étape 1 : Ouvrir la section des clés API

Allez à Paramètres → Compte → Sécurité & accès (/settings/account/security)
Trouvez la carte Clés API personnelles
Cliquez sur Nouvelle clé API

Page Paramètres → Compte → Sécurité & accès montrant la carte Clés API personnelles avec les clés existantes et le bouton Nouvelle clé API — La page Sécurité & accès est l'endroit où vous créez et gérez vos clés API personnelles.

Étape 2 : Configurer la clé

Le formulaire de création demande trois choses :

┌─────────────────────────────────────────────────────┐
│ Créer une clé API                                   │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Nom de la clé                                       │
│ [ Intégration de production                ]        │
│                                                     │
│ Permissions                                         │
│ ● Accès complet                                     │
│ ○ Uniquement les permissions sélectionnées…         │
│     ☐ Lire  ☐ Écrire  ☐ Admin                      │
│                                                     │
│ Accès à l'équipe                                    │
│ ● Toutes les équipes auxquelles vous avez accès    │
│ ○ Uniquement les équipes sélectionnées…             │
│                                                     │
│ [Annuler] [Créer]                                   │
└─────────────────────────────────────────────────────┘

Permissions contrôle ce que la clé peut faire. Accès complet accorde tous les niveaux ; ou choisissez les niveaux individuels (Lire, Écrire, Admin). L'API externe est en lecture seule aujourd'hui, donc une clé Lire est suffisante pour l'analytique.
Accès à l'équipe contrôle quels espaces de travail la clé peut atteindre. Laissez-le sur Toutes les équipes auxquelles vous avez accès, ou limitez-le à des équipes spécifiques.

Étape 3 : Enregistrez votre clé

Important : la clé complète n'est affichée qu'une seule fois. Copiez-la avant de fermer le dialogue.

┌─────────────────────────────────────────────────────┐
│ Votre nouvelle clé API                              │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Cette clé API ne sera plus visible à l'avenir.     │
│ Veuillez la copier maintenant.                      │
│                                                     │
│ zv_abc123xyz789...                                 │
│                                                     │
│ [Copier]                                            │
│                                                     │
└─────────────────────────────────────────────────────┘

Format de la clé

Toutes les clés API utilisent un seul format :

Préfixe : zv_
Les clés sont stockées sous forme de hachages SHA-256 pour la sécurité
La clé complète n'est affichée qu'une seule fois au moment de la création

Il n'existe pas de type de clé test/sandbox séparé. Pour séparer le développement et la production, créez plusieurs clés avec des noms descriptifs.

Permissions des clés

Lorsque vous créez une clé, vous choisissez ses permissions (portées) et son accès à l'équipe.

Portée	Ce qu'elle accorde
Accès complet	Chaque portée
Lire	Accès en lecture seule à l'API externe
Écrire	Points de terminaison d'écriture (`POST`/`PATCH`/`DELETE`)
Admin	Points de terminaison réservés aux administrateurs (nécessite le rôle propriétaire ou administrateur sur l'équipe)

La surface API externe documentée ci-dessous est en lecture seule aujourd'hui, donc une clé Lire (ou Accès complet) est tout ce dont vous avez besoin pour l'analytique. L'ingestion de suivi n'utilise pas du tout de clé API ; elle utilise le script de suivi.

À quoi les clés API peuvent accéder

Catégorie de point de terminaison	Points de terminaison
Analytique	GET /analytics/:websiteId (aperçu, visiteurs, pages, pays, technologie)
Sites web	GET /websites, GET /websites/:websiteId
Heatmaps	GET /heatmaps/:websiteId/pages
Enregistrements de session	GET /replays/:websiteId/sessions
Groupes d'erreurs	GET /errors/:websiteId/groups
Utilisation	GET /usage

Restrictions d'accès à l'équipe

Toutes les équipes

Par défaut, une clé peut atteindre chaque équipe (espace de travail) à laquelle votre compte appartient, et chaque site web à l'intérieur :

Configuration la plus simple
Idéale pour les outils internes qui lisent sur vos espaces de travail

Équipes sélectionnées

Pour limiter une clé, choisissez Uniquement les équipes sélectionnées… et sélectionnez les équipes qu'elle peut atteindre. La clé fonctionne alors uniquement pour les sites web appartenant à ces équipes.

Cas d'usage pour les restrictions

Scénario	Paramètre
Clé pour un seul espace de travail	Équipes sélectionnées (choisir cet équipe)
Tableau de bord interne dans tous vos espaces de travail	Toutes les équipes auxquelles vous avez accès

Gestion des clés

Voir toutes les clés

La carte Clés API personnelles liste chaque clé avec sa portée, son préfixe masqué et sa dernière heure d'utilisation :

┌─────────────────────────────────────────────────────┐
│ Clés API personnelles             [+ Nouvelle clé] │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Production    [Accès complet]   zv_abc…            │
│ Dashboard     [Lire]            zv_def…            │
│ Client A      [Lire]            zv_ghi…            │
│                                                     │
└─────────────────────────────────────────────────────┘

Détails de la clé

Cliquez sur une clé pour ouvrir sa vue détaillée :

Nom, portée et accès à l'équipe
Horodatages de création et de dernier usage
Activité côté serveur (comptes d'événements acceptés et événements récents pour cette clé)

Modifier une clé

Dans la vue détaillée, sélectionnez Modifier dans le menu (bouton …) pour renommer la clé ou modifier ses portées et accès à l'équipe, puis enregistrez.

Révoquer une clé

Si une clé est compromise ou non utilisée :

Ouvrez la vue détaillée de la clé
Dans le menu …, cliquez sur Révoquer
Confirmez

La clé est immédiatement invalidée. Pour remplacer une clé, révoquez l'ancienne et créez une nouvelle.

Sécurité des clés

Bonnes pratiques

Pratique	Pourquoi
Utiliser les variables d'environnement	Ne pas coder en dur
Accorder la portée et l'accès à l'équipe les plus étroits	Limiter le rayon d'impact
Clés séparées par intégration	Isoler dev/prod et clients
Révoquer les clés inutilisées	Réduire l'exposition
Surveiller la vue d'activité	Détecter les anomalies

Variables d'environnement

Stockez les clés de manière sécurisée :

# Fichier .env (ne jamais commiter !)
ZENOVAY_API_KEY=zv_abc123...

// Utiliser dans le code
const apiKey = process.env.ZENOVAY_API_KEY;

Rotation des clés

Zenovay ne régénère pas une clé sur place. Pour effectuer une rotation :

Créez une nouvelle clé
Mettez à jour vos applications pour l'utiliser
Vérifiez que tout fonctionne
Révoquez l'ancienne clé

Utiliser les clés API

cURL

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
  headers: {
    'X-API-Key': process.env.ZENOVAY_API_KEY,
  }
});

Python

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/websites',
    headers={'X-API-Key': api_key}
)

Dépannage

L'API retourne des erreurs dans la forme { "error": { "message": "...", "code": "..." } }.

Clé API manquante ou invalide

{
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}

Retourne 401. Vérifiez :

La clé est copiée correctement, avec le préfixe zv_
Pas d'espaces ou de sauts de ligne supplémentaires
La clé n'a pas été supprimée
Vous l'avez envoyée en tant que X-API-Key ou Authorization: Bearer

Le plan ne comprend pas l'accès à l'API

{
  "error": {
    "message": "The Zenovay API requires a paid plan. Upgrade to Pro or higher to use API keys.",
    "code": "API_PAID_PLAN_REQUIRED"
  }
}

Retourne 403. L'API externe nécessite un plan Pro ou supérieur. Mettez à niveau votre espace de travail, puis créez une clé.

Interdit pour ce site web

{
  "error": {
    "message": "Forbidden",
    "code": "FORBIDDEN"
  }
}

Retourne 403. La clé n'a pas accès au site web demandé, car le site web appartient à une équipe en dehors de l'accès à l'équipe de la clé. Utilisez une clé dont l'accès à l'équipe couvre ce site web, ou élargissez l'accès à l'équipe de la clé.

Activité & Utilisation

Ouvrez la vue détaillée d'une clé pour voir son activité côté serveur : comptes d'événements acceptés (dernières 24 heures, derniers 7 jours et tous les temps) et les événements les plus récents attribués à cette clé. C'est utile pour confirmer qu'une clé est en direct et détecter une utilisation inattendue.