Identifiants bots et webhooks

Chaque bot a ses propres identifiants, distincts de la clé API de l'organisation partenaire.

Modèle de sécurité (recommandé)

Identifiant	Objectif	Stockage
Clé API partenaire (sk_…)	Gérer tous les bots, faire tourner les secrets, envoyer les messages hub	Hashé au repos
Token bot (bot_….…)	Appels API limités au bot (webhook entrant, futures API bot)	Hashé au repos · affiché une seule fois
Secret webhook (whsec_…)	Signer / vérifier les corps de webhook en HMAC	Stocké (nécessaire pour signer) · traiter comme un mot de passe
URL webhook	Endpoint HTTPS partenaire pour les événements MorisBox	URL en clair

Pourquoi pas client_id + client_secret OAuth ?

Les client credentials OAuth conviennent mieux à un accès délégué par l'utilisateur. Les bots sont machine-à-machine ; un seul token bot à haute entropie + des signatures HMAC sur les webhooks est plus simple et plus robuste pour ce cas d'usage.

Bons réflexes

1. Webhooks HTTPS uniquement (localhost autorisé en dev)
2. Signatures de corps HMAC-SHA256 sur chaque événement sortant
3. Allowlist IP optionnelle par bot
4. Rotation du token / secret sans recréer le bot
5. Ne jamais journaliser les tokens complets

---

Créer un bot (secrets renvoyés une fois)

POST /api/v1/bots

{
  "code": "portail",
  "name": "SEED Portail",
  "runtime_mode": "local",
  "webhook_url": "https://partner.example/hooks/morisbox/portail"
}

Réponse 201

{
  "bot": {
    "code": "portail",
    "credentials": {
      "token_prefix": "bot_a1b2c3",
      "token_configured": true,
      "webhook_url": "https://partner.example/hooks/morisbox/portail",
      "webhook_secret_prefix": "whsec_ab12",
      "inbound_webhook_path": "/api/v1/bots/portail/webhook"
    }
  },
  "bot_token": "bot_a1b2c3d4e5f6.xxxxxxxx",
  "webhook_secret": "whsec_xxxxxxxx",
  "warning": "Store bot_token and webhook_secret now…"
}

Enregistrez bot_token et webhook_secret dans votre gestionnaire de secrets. Ils ne peuvent pas être relus ensuite, uniquement régénérés par rotation.

---

Gérer les identifiants

Méthode	Path	Auth	Description
GET	/bots/{code}/credentials	Clé partenaire ou token bot	Préfixes uniquement
POST	/bots/{code}/token/rotate	Clé partenaire	Nouveau bot_token (une fois)
PUT	/bots/{code}/webhook	Clé partenaire	Définir webhook_url, option rotate_secret
POST	/bots/{code}/webhook/secret/rotate	Clé partenaire	Nouveau secret webhook
POST	/bots/{code}/webhook/test	Clé partenaire	Envoyer un événement de test signé
PATCH	/bots/{code}	Clé partenaire	Mettre à jour nom, canaux, allowed_ips, …

Définir le webhook

PUT /api/v1/bots/portail/webhook
Authorization: Bearer sk_…

{
  "webhook_url": "https://partner.example/hooks/morisbox/portail",
  "rotate_secret": true,
  "allowed_ips": "203.0.113.10"
}

---

Webhooks sortants (MorisBox → vous)

Lorsque MorisBox poste vers votre webhook_url :

POST https://partner.example/hooks/morisbox/portail
Content-Type: application/json
X-Seed360-Event: bot.webhook.test
X-Seed360-Bot: portail
X-Seed360-Signature: sha256=<hex>
X-Seed360-Bot-Secret: <webhook_secret>

Corps

{
  "event": "bot.webhook.test",
  "bot": {
    "ref": "…",
    "code": "portail",
    "partner_code": "seed"
  },
  "payload": {}
}

Vérifier la signature (Python)

import hmac, hashlib

def verify(raw_body: bytes, header_sig: str, secret: str) -> bool:
    sig = header_sig.removeprefix("sha256=")
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Préférez vérifier le HMAC plutôt que de vous fier uniquement à l'en-tête secret.

---

Webhooks entrants (vous → MorisBox)

POST /api/v1/bots/{code}/webhook

Authentifiez-vous avec l'une des méthodes suivantes :

1. Authorization: Bearer <bot_token>
2. X-Seed360-Bot-Secret: <webhook_secret>
3. X-Seed360-Signature: sha256=<hmac of body with webhook_secret>

{
  "event": "custom.event",
  "data": { "ok": true }
}

---

Utiliser le token bot

GET /api/v1/bots/portail
Authorization: Bearer bot_a1b2c3d4e5f6.xxxx

Les tokens bot sont limités à ce bot. Les clés API partenaires gèrent toute l'organisation.

---

Checklist opérationnelle

1. Créer le bot → enregistrer bot_token + webhook_secret
2. Déployer le récepteur HTTPS → PUT …/webhook
3. POST …/webhook/test jusqu'à ok: true
4. En cas de fuite, rotation via token/rotate / webhook/secret/rotate