Authentification

Format de clé

Toutes les clés émises depuis 2026-05 respectent le format cap_live_<64 hex>. Le format legacy cap_<64 hex> reste accepté jusqu'au 2027-05-03 (un banner dans le dashboard signale les clés legacy).

Header Authorization

Toutes les requêtes vers /v1/* doivent inclure un header Bearer. Aucun fallback querystring ni cookie.

Authorization: Bearer cap_live_<your-key>

Header absent

Pas de header Authorization dans la requête. Code retour : 401 missing_api_key.

Clé invalide

Clé inconnue, mal formée, ou hash non reconnu. Code retour générique 401 invalid_api_key (pour ne pas leak quelle partie de la clé est fautive).

Clé expirée

La clé a passé sa date d'expiration. Code retour 401 expired_api_key. Génère une nouvelle clé via le dashboard.

Clé révoquée

La clé a été révoquée explicitement (action admin ou roll). Code retour 401 revoked_api_key. Le request_id permet à notre support de retrouver l'événement de révocation.

Scopes et presets

Une clé porte des scopes (permissions techniques). Pour faciliter, l'UI propose 5 presets qui regroupent les scopes par cas d'usage.

Scopes individuels

• contacts:read — Lire les contacts
• contacts:write — Créer/modifier contacts
• pipeline:read — Lire le pipeline
• pipeline:write — Modifier le pipeline
• conversations:read — Lire conversations
• bookings:read — Lire RDV
• bookings:write — Créer/modifier RDV
• quotes:read — Lire soumissions
• quotes:write — Créer/modifier soumissions
• tags:read — Lire tags
• tags:write — Créer/modifier tags
• automations:read — Lire automatisations
• automations:trigger — Déclencher automatisations
• email:send — Envoyer email
• email:read — Lire conversations email
• webhooks:manage — Gérer webhooks
• leads:capture — Capturer leads externes (CASL gated)
• events:ingest — Pousser des événements entrants
• campaigns:launch — Lancer des campagnes SMS (confirmation en 2 temps)

Conditions CASL / Loi 25

Le scope leads:capture est gated derrière une attestation que tu acceptes au moment de créer la clé. Cette attestation engage formellement : chaque lead poussé via cet endpoint a donné son consentement explicite pour recevoir des SMS commerciaux. Capturia conserve la trace horodatée (IP, navigateur, version).

Forfait et fonctionnalités

Chaque requête est aussi validée contre le forfait du compte. Si l'accès n'est pas inclus dans ton forfait, la requête est refusée avec 403 feature_not_available — même si la clé est valide et possède le scope requis. L'API publique et le connecteur assistant IA sont deux accès distincts, chacun validé contre sa propre fonctionnalité de forfait (le champ details.feature de l'erreur nomme celle qui manque). Le refus vient du forfait, pas de la clé : générer une nouvelle clé ou modifier ses scopes ne change rien. Contacte ton conseiller Capturia pour faire évoluer ton forfait.

Brute force et clés invalides

10 tentatives consécutives avec clé invalide depuis la même IP en 5 minutes → blocage IP pendant 5 minutes (429 too_many_attempts avec Retry-After: 300). Cette politique protège les clés contre l'énumération.

Bonnes pratiques sécurité

• Jamais en frontend. L'API est serveur-à-serveur. Une clé exposée dans un navigateur est une fuite immédiate.

• Stocke en variable d'environnement (jamais committé dans le repo).

• Une clé par intégration — n'utilise pas la même clé pour Zapier et ton code custom. En cas de fuite, tu peux révoquer une intégration sans casser les autres.

• Rotation régulière — utilise le Roll flow pour renouveler sans interruption (12h overlap).

• Aucun CORS public — tu ne peux pas appeler l'API depuis un navigateur, c'est intentionnel.