API d’intégration et webhooks
Authentification Bearer, contrats exécutables et vérification des signatures.
Sur cette page
Authentification et plafond de scopes
Les 25 routes Bearer portent leur authentification dans OpenAPI. Les droits effectifs sont l’intersection des scopes du jeton et des permissions actuelles de son propriétaire. Le plafond est conservé dans les helpers asynchrones, y compris les hooks. Le code JavaScript de confiance n’est pas isolé dans une sandbox.
N’envoyez aucun Cookie avec Authorization. Les sessions du navigateur conservent Origin exact et CSRF. Les jetons ne donnent pas accès aux comptes, aux réglages, aux packages ou à la création d’autres jetons. Limites : 900 authentifications par jeton et 5 000 par adresse socket sur quinze minutes.
const response = await fetch("https://cms.example.com/api/v1/content?page=1", {
headers: { authorization: "Bearer " + process.env.CMS_API_TOKEN },
});
if (!response.ok) throw new Error("CMS request failed: " + response.status);
const contents = await response.json();Contrats publiés et limites
Les 12 routes de gestion des intégrations et les 25 routes Bearer ont des schémas de requêtes et de réponses appliqués à l’exécution. Les documents et définitions de champs sont récursifs. Les règles métier, les références et les schémas de valeurs propres à chaque type restent validés par les services.
Signature du corps brut
| En-tête | Usage |
|---|---|
| x-bracten-id | Identifiant de livraison stable pendant les reprises. |
| x-bracten-timestamp | Secondes Unix, renouvelées à chaque tentative. |
| x-bracten-secret-version | Version du secret à sélectionner. |
| x-bracten-signature | v1= suivi du HMAC-SHA-256 hexadécimal. |
Le HMAC porte sur timestamp + point + deliveryId + point + corps JSON brut. Utilisez le secret affiché comme texte, sans décodage base64. Comparez avec timingSafeEqual, vérifiez une fenêtre de cinq minutes et dédupliquez durablement la livraison. Le guide source docs/integrations.md fournit le récepteur Node complet.
Outbox et sécurité réseau
Les événements contenu et création de compte sont inscrits dans la même transaction que l’écriture. Le dispatcher crée les livraisons et jobs durables sans doublon logique. Le transport livre au moins une fois ; une acceptation distante suivie d’une coupure locale peut répéter la requête.
Cinq tentatives automatiques précèdent la reprise manuelle. Une configuration ou version de secret différente annule l’ancienne demande. HTTPS 443 uniquement, toutes les IP DNS contrôlées, connexion sur l’IP vérifiée, pas de redirect ni proxy, dix secondes de délai total et aucun corps de réponse conservé.
Les secrets sont chiffrés AES-GCM avec une clé dérivée de CMS_BACKUP_KEY et liés par AAD au webhook et à sa version de secret. Après restauration, les accès et envois restaurés sont neutralisés. Les suites de test utilisent un récepteur substitué sans envoi vers un tiers.