Laissez un agent provisionner tout le pipeline

Un agent ne fait rien ici tant que vous ne lui avez pas remis une clé. Créer le compte, vérifier l’e-mail du propriétaire et créer cette clé se font dans le navigateur, et c’est tout l’intérêt : la personne responsable de la relation de facturation décide de ce que l’agent peut atteindre, et l’agent détient un seul identifiant, visible dans une liste et révocable en un clic.

Cela évite aussi de jongler avec des jetons. L’agent ne touche jamais à un point de terminaison de compte, ne détient jamais de session et ne peut pas élargir son propre accès. Tout ce qu’il fait passe par /v1/* avec la clé que vous lui avez donnée.

Dans le tableau de bord, sous Organisation → Clés d’API, Nouvelle clé demande un nom, une expiration facultative et Accès aux projets. Laissez Tous les projets et la clé atteint tout ce que contient l’organisation. Choisissez-en un et la clé y est liée : c’est ainsi que vous gardez une exécution autonome dans un périmètre que vous avez choisi. La valeur n’apparaît qu’une fois, copiez-la donc directement dans l’environnement de l’agent.

Le tableau de bord crée et révoque les clés, mais ne modifie pas leur portée : élargir ou restreindre une liaison plus tard revient à créer une clé de remplacement et à retirer l’ancienne. Des permissions par action et par clé sont prévues. En attendant, une clé porte les permissions de niveau membre : elle lit tout ce qui est dans sa portée et peut librement créer, mettre à jour, activer ou désactiver, relancer et rejouer, tandis que les suppressions, l’affichage et le renouvellement du secret de signature, la rotation de masque, le provisionnement de connecteurs et les changements de facturation restent réservés à un administrateur ou un propriétaire dans le tableau de bord.

Trois appels : une source pour recevoir, une destination vers laquelle envoyer, et une connexion qui les relie. La réponse de la source contient l’ingestUrl, la seule chose dont votre fournisseur a besoin.

# Source. The ingestUrl is what your provider gets.curl -s "$API/v1/sources" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Stripe", "provider": "stripe", "verifierConfig": { "secret": "whsec_..." } }'→ { "id": "src_...", "ingestUrl": "https://sdhk.events/<maskId>", ... } # Destination, then a connection joining the two.curl -s "$API/v1/destinations" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Billing", "type": "http", "url": "https://acme.example/hooks" }' curl -s "$API/v1/connections" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Stripe → Billing", "sourceId": "src_...", "destinationId": "dest_..." }'

Indiquer un fournisseur connu apporte son schéma de signature : l’agent fournit un secret au lieu de rechercher un format de signature. Les sources acceptent aussi les e-mails entrants, que couvre le guide consacré à l’e-mail.

Un agent qui ne peut qu’écrire avance à l’aveugle. La même API renvoie chaque événement avec le résultat de sa vérification et chaque livraison avec ses tentatives, ce qui rend possible le débogage d’une exécution autonome.

Un échec de signature renvoie à l’appelant un 401 volontairement vague, car expliquer à un expéditeur non authentifié quel contrôle a échoué transformerait la réponse en oracle. La raison est plutôt enregistrée sur l’événement, où un agent authentifié peut la lire.

# Why did nothing arrive?curl -s "$API/v1/events?status=rejected" -H "authorization: Bearer $SDHK_KEY"→ rejectionReason: "signature_mismatch" | "timestamp_out_of_tolerance" | ... # Re-send one failed delivery. Free, creates nothing new.curl -s -X POST "$API/v1/deliveries/dlv_.../retry" -H "authorization: Bearer $SDHK_KEY" # Run an event through its connections again. Billable.curl -s -X POST "$API/v1/events/evt_.../replay" -H "authorization: Bearer $SDHK_KEY"

• /v1/spec.json est le schéma OpenAPI 3 de chaque point de terminaison, et /v1 la référence interactive basée sur la même spécification.
• /llms.txt oriente rapidement un modèle. /llms-full.txt est le guide complet, y compris la sémantique des erreurs et les limites qui comptent.
• Les erreurs sont typées plutôt que rédigées. QUOTA_EXCEEDED et RATE_LIMITED sont des codes distincts sur lesquels brancher directement. Les erreurs de limite de plan, comme un plafond de connecteurs, restent sous FORBIDDEN, avec un payload data (limit, current) qui porte les détails.

• Donnez à chaque agent sa propre clé. En révoquer une ne vous coûte alors rien d’autre, et la colonne de dernière utilisation vous indique quel agent s’est tu.
• Liez la clé à un projet, sauf si l’agent gère réellement des projets. C’est la seule portée disponible aujourd’hui, et elle ne peut pas être modifiée après la création de la clé.
• Branchez sur le code d’erreur, jamais sur le texte du message. Les messages sont écrits pour des humains et le 401 de l’ingestion est volontairement peu informatif.
• Consultez ?status=rejected avant de renvoyer quoi que ce soit. Une signature qui n’a jamais été vérifiée ne le sera pas davantage à la deuxième tentative.
• Préférez la relance d’une livraison au rejeu d’un événement quand un seul consommateur a échoué. La relance est gratuite, le rejeu est facturé.