Documentation · API
API publique
01 · Démarrage
Cinq minutes, REST et JSON
L’API publique ConsentLab (/v1) expose vos statistiques de consentement, votre registre, la configuration du bandeau et le déclenchement de scans, en REST/JSON authentifié par clé. Elle est incluse sur les plans Business (site ≥ 500 000 sessions) et Agence.
La référence complète et interactive vit sur /v1/docs, le schéma OpenAPI brut sur /v1/openapi.json. Cette page est un guide rédigé : en cas de doute sur un champ exact, ces deux ressources font foi.
Ouvrir la doc interactive /v1/docsSchéma OpenAPI /v1/openapi.json
Créer une clé API
Depuis votre dashboard (Paramètres → API), créez une clé en choisissant les scopes (droits) dont vous avez besoin et le ou les Sites qu’elle pourra atteindre. La clé, au format cl_live_…, n’est affichée qu’une seule fois : copiez-la immédiatement dans un gestionnaire de secrets.
Premier appel authentifié
Chaque requête porte l’en-tête Authorization: Bearer cl_live_… (snippet à droite). L’id de site renvoyé sert de paramètre à tous les autres endpoints. Un environnement de staging est disponible pour vos tests.
02 · Recettes
Trois cas d’usage, trois scripts
Reporting agence
Pour un tableau de bord client, croisez les agrégats (consent-stats : taux d’acceptation, volumes) avec le détail au besoin (consents).
Archivage du registre
Pour conserver la preuve de consentement dans votre propre entrepôt, paginez consents par curseur (limit ≤ 100) jusqu’à épuisement (script à droite).
Configuration du bandeau en CI/CD
Versionnez la configuration de vos bandeaux et appliquez-la depuis votre pipeline avec PUT banner-config. Stockez la clé en variable d’environnement chiffrée de votre CI (secret), jamais dans le dépôt : une clé write:config ne peut rien lire ni supprimer d’autre, c’est le principe du moindre privilège.
03 · Endpoints
Six endpoints, tout le périmètre v1
Six endpoints couvrent tout le périmètre v1. Le détail des paramètres et des schémas de réponse est sur la doc interactive /v1/docs ; les scopes indiqués correspondent au contrat v1, la doc interactive fait foi si un endpoint évolue.
| Méthode | Chemin | Scope requis | Description |
|---|---|---|---|
| GET | /v1/sites | aucun | Liste des sites accessibles à la clé. |
| GET | /v1/sites/:id/consent-stats | read:stats | Agrégats de consentement (taux, volumes). |
| GET | /v1/sites/:id/consents | read:consents | Registre des consentements, paginé par curseur. |
| GET | /v1/sites/:id/banner-config | read:config / write:config | Configuration actuelle du bandeau. |
| PUT | /v1/sites/:id/banner-config | write:config | Met à jour la configuration du bandeau. |
| POST | /v1/sites/:id/scans | trigger:scan | Déclenche un scan de cookies du site. |
04 · Limites
Erreurs, rate-limit, pagination
Codes d’erreur
Les erreurs suivent les statuts HTTP standards, avec un code machine stable dans le corps JSON. Pour VALIDATION_FAILED, il est dans le champ code ; les autres codes ci-dessous sont la valeur du champ message.
| HTTP | Code d’erreur | Cause |
|---|---|---|
| 400 | VALIDATION_FAILED | Requête invalide (paramètre manquant ou mal formé). Le détail des champs est dans <code>message</code> (tableau). |
| 401 | INVALID_API_KEY | Clé absente, malformée, révoquée ou expirée. |
| 403 | INSUFFICIENT_SCOPE | La clé n’a pas le scope requis par l’endpoint. |
| 403 | API_ACCESS_REQUIRED | Le plan n’inclut pas l’accès API (Business ≥ 500k ou Agence). |
| 403 | IP_NOT_ALLOWED | Appel émis depuis une IP hors de l’allowlist configurée sur la clé. |
| 404 | SITE_NOT_FOUND | Site inexistant ou hors du périmètre de la clé. |
| 404 | CONFIG_NOT_FOUND | Aucune configuration de bandeau n’existe encore pour ce site. |
| 429 | RATE_LIMIT_EXCEEDED | Débit dépassé : voir Retry-After. |
Rate-limit
Chaque réponse porte les en-têtes de quota (exemple à droite). Les planchers garantis sont de 300 requêtes/min/IP et 600 requêtes/min/clé ; X-RateLimit-Reset est exprimé en secondes restantes. Les compteurs sont partagés entre toutes nos instances : les limites sont donc exactes et appliquées à la vraie IP client, sans dérive due à la répartition de charge.
Sur un 429 RATE_LIMIT_EXCEEDED, respectez l’en-tête Retry-After avant de réessayer (backoff). Ne bouclez pas sans attendre : vous resteriez bloqué.
Pagination par curseur
Les collections volumineuses (consents) se parcourent par curseur : ?cursor=&limit= avec limit plafonné à 100. Renvoyez le curseur de la page précédente jusqu’à ce qu’il soit vide (voir la recette d’archivage ci-dessus). Le curseur est opaque : ne le construisez pas à la main.
05 · Versionnement
v1 dans le chemin, 12 mois de préavis
L’API est versionnée dans le chemin (/v1/). Les évolutions rétro-compatibles (nouveaux champs, nouveaux endpoints) arrivent sans changer de version ; toute évolution cassante passerait par une nouvelle version (/v2/).
Politique de dépréciation : 12 mois. Si une version ou un endpoint est déprécié, il reste servi au moins 12 mois après l’annonce, le temps de migrer sereinement.
Changelog
v1 : version initiale. Clés API scoppées par Site, endpoints sites, consent-stats, consents, banner-config, scans, pagination par curseur et rate-limit.
06 · Sécurité
Des clés qui ne fuitent pas
- Format et affichage unique · Une clé
cl_live_…n’est montrée qu’à sa création. Nous n’en stockons qu’une empreinte : impossible de la ré-afficher. - Moindre privilège · N’accordez que les scopes nécessaires parmi les cinq existants (
read:stats,read:consents,read:config,write:config,trigger:scan). Un job de reporting n’a besoin que de lecture ; pour relire la config du bandeau sans pouvoir la modifier,read:configsuffit. - Scoping par Site · Une clé ne peut atteindre que les Sites auxquels vous l’avez rattachée. Créez une clé par intégration plutôt qu’une clé passe-partout.
- Durée de vie (TTL) · À la création, fixez une expiration (
expiresInDays, de 1 à 3650 jours). Passé ce délai, la clé est automatiquement rejetée (401 INVALID_API_KEY) : idéal pour les accès temporaires (audit, prestataire, POC). - Rotation en deux temps · Créez la nouvelle clé, déployez-la, puis révoquez l’ancienne. Une période de grâce de 24 h laisse vos services basculer sans coupure.
- Révocation immédiate · Une clé révoquée cesse de fonctionner sur-le-champ (
401 INVALID_API_KEY). Révoquez au moindre doute. - Auto-révocation en cas de fuite · Nos préfixes de clés (
cl_live_…) sont enregistrés auprès du secret scanning de GitHub. Si une clé est poussée par erreur sur un dépôt public, nous sommes alertés et la clé est révoquée automatiquement : une clé fuitée ne reste pas exploitable. - Ne commitez jamais une clé · Variable d’environnement ou gestionnaire de secrets, jamais dans le dépôt ni dans du code front-end (les clés sont serveur-à-serveur).
Restreindre une clé à des IP
Vous pouvez restreindre une clé à une liste d’adresses IP ou de plages CIDR sources (IPv4 et IPv6). Tout appel provenant d’une IP hors de cette allowlist est refusé avec un 403 IP_NOT_ALLOWED, quelle que soit la validité de la clé. Idéal pour épingler une intégration serveur à l’IP de sortie fixe de votre infrastructure ou de votre runner CI.
Puis-je utiliser une clé API dans mon front-end ?
Non. Les clés cl_live_… sont serveur-à-serveur : exposées côté client, elles seraient volées. Pour le bandeau côté navigateur, c’est l’identifiant public du widget (data-cc-key) qui est utilisé, voir l’onglet Installation.
J’ai perdu ma clé, comment la retrouver ?
On ne peut pas la ré-afficher (nous n’en gardons qu’une empreinte). Créez-en une nouvelle avec les mêmes scopes, déployez-la, puis révoquez l’ancienne.
Quel plan donne accès à l’API ?
L’accès API est inclus sur les plans Business (site ≥ 500 000 sessions/mois) et Agence. Sur un plan sans accès, les endpoints renvoient 403 API_ACCESS_REQUIRED.
Prêt à automatiser votre conformité ?
Créez une clé depuis votre dashboard, ou explorez la référence interactive de l’API.
Premier appel
# Authentifiez chaque requête avec l'en-tête Authorization: Bearer curl "https://api.consentlab.eu/v1/sites" \ -H "Authorization: Bearer $CONSENTLAB_API_KEY"
Réponse
[
{ "id": "3f2a9c7e-1b4d-4e8a-9f2c-7a1b2c3d4e5f", "name": "monsite.fr", "created_at": "2026-01-15T09:24:00Z" }
]Environnements
# Production https://api.consentlab.eu/v1 # Staging (pré-production) https://dev.api.consentlab.eu/v1
Reporting agence
# Agrégats de consentement d'un site (taux d'acceptation, volumes…) curl "https://api.consentlab.eu/v1/sites/3f2a9c7e-1b4d-4e8a-9f2c-7a1b2c3d4e5f/consent-stats" \ -H "Authorization: Bearer $CONSENTLAB_API_KEY" # scope: read:stats
Archivage du registre
#!/usr/bin/env bash # Exporte tout le registre des consentements en JSON Lines, page par page. # La clé vit dans une variable d'environnement, jamais en dur dans le script. SITE="3f2a9c7e-1b4d-4e8a-9f2c-7a1b2c3d4e5f" cursor="" while : ; do resp=$(curl -s "https://api.consentlab.eu/v1/sites/$SITE/consents?limit=100&cursor=$cursor" \ -H "Authorization: Bearer $CONSENTLAB_API_KEY") # scope: read:consents echo "$resp" | jq -c '.data[]' >> registre.jsonl # Champ de pagination exact : voir /v1/openapi.json cursor=$(echo "$resp" | jq -r '.next_cursor // empty') [ -z "$cursor" ] && break done
Config en CI/CD
# Applique la config du bandeau depuis votre pipeline (scope: write:config). # Le corps JSON est illustratif, schéma exact : /v1/openapi.json curl -X PUT "https://api.consentlab.eu/v1/sites/3f2a9c7e-1b4d-4e8a-9f2c-7a1b2c3d4e5f/banner-config" \ -H "Authorization: Bearer $CONSENTLAB_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "primary_color": "#0F766E", "position": "bottom" }'
En-têtes de rate-limit
HTTP/1.1 200 OK X-RateLimit-Limit: 600 X-RateLimit-Remaining: 598 X-RateLimit-Reset: 42 # secondes avant remise à zéro # En cas de 429, l'en-tête Retry-After indique combien de temps attendre.