API publique ConsentLab

1. Démarrage en 5 minutes

L'API publique ConsentLab (/v1) expose vos statistiques de consentement, votre registre, la configuration du bandeau et le déclenchement de scans — le tout en REST/JSON, authentifié par clé. Elle est incluse sur les plans Business (site ≥ 500 000 sessions) et Agence.

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(s) Site(s) 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_…. Listons vos sites :

# 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" }
]

L'id de site (ex. 3f2a9c7e-1b4d-4e8a-9f2c-7a1b2c3d4e5f) sert de paramètre à tous les autres endpoints. Un environnement de staging est disponible pour vos tests :

# Production
https://api.consentlab.eu/v1
# Staging (pré-production)
https://dev.api.consentlab.eu/v1

2. Recettes par cas d'usage

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) :

# 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

Pour conserver la preuve de consentement dans votre propre entrepôt, paginez consents par curseur (limit≤ 100) jusqu'à épuisement :

#!/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

Configuration du bandeau en CI/CD

Versionnez la configuration de vos bandeaux et appliquez-la depuis votre pipeline avec PUT banner-config :

# 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" }'

3. Référence des endpoints

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.

Les scopes indiqués correspondent au contrat v1 ; la doc interactive fait foi si un endpoint évolue.

4. Limites & erreurs

Codes d'erreur

Les erreurs suivent les statuts HTTP standards, avec un code machine stable dans le corps JSON :

Rate-limit

Chaque réponse porte les en-têtes de quota. 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.

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.

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.

5. Versionnement & dépréciation

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/).

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.

6. Sécurité des clés

• Format & 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:config suffit.
• 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 CIDRsources (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.