Dvina MCP

Utiliser l’accès à l’API

Créez des jetons d’accès personnels pour vos scripts et clients MCP, et envoyez les événements de votre Livespace à vos propres systèmes à l’aide de webhooks.

Voir en Markdown

Dans Réglages › Accès à l’API, créez des jetons d’accès personnels pour permettre à un script ou à un client MCP d’utiliser Dvina en votre nom. Les administrateurs peuvent aussi y ajouter des webhooks pour envoyer les événements du Livespace à leurs propres systèmes.

L’accès à l’API est inclus dans l’offre Enterprise. Chaque membre peut créer ses propres jetons ; seuls les propriétaires et les administrateurs voient la section Webhooks.

Créer un jeton

  1. Ouvrez Réglages et choisissez Accès à l’API.
  2. Sous Jetons d’accès personnels, choisissez Créer un jeton.
  3. Saisissez un Nom pour pouvoir identifier plus tard ce qui utilise ce jeton.
  4. Choisissez le niveau d’Accès : Lecture seule ou Lecture et écriture.
  5. Choisissez la date d’Expiration : Dans 30 jours, Dans 90 jours, Dans 365 jours ou N’expire jamais.
  6. Choisissez Créer un jeton.
  7. Sous Copier votre jeton, copiez le jeton et conservez-le en lieu sûr. Il ne s’affiche qu’une seule fois.

Un jeton agit en votre nom, dans le Livespace où vous l’avez créé, avec le rôle que vous y détenez actuellement. Un jeton en Lecture seule permet de lire les données, mais pas d’ajouter ni de modifier quoi que ce soit.

Pour utiliser un jeton avec un client MCP, consultez Se connecter avec une clé API plutôt qu’avec OAuth.

Consulter, renouveler ou révoquer un jeton

Vos jetons sont répertoriés sous Jetons d’accès personnels, avec leur niveau d’accès. Choisissez un jeton pour voir ses premiers caractères dans Commence par, son niveau d’Accès, sa Dernière utilisation et sa date d’Expiration.

  • Pour remplacer un jeton, choisissez Renouveler…, puis Renouveler pour confirmer. Un nouveau jeton le remplace et l’ancien cesse immédiatement de fonctionner. Copiez le nouveau jeton sous Copier votre jeton.
  • Pour désactiver un jeton, choisissez Révoquer…, puis Révoquer pour confirmer. Tout ce qui l’utilise cesse immédiatement de fonctionner.

La création, le renouvellement et la révocation d’un jeton sont consignés dans le journal d’audit.

Ajouter un webhook

Un webhook envoie les événements du Livespace à l’adresse de votre choix. Il s’agit des mêmes enregistrements que ceux du journal d’audit.

  1. Dans Réglages › Accès à l’API, sous Webhooks, choisissez Ajouter un webhook.
  2. Saisissez un Nom et l’URL. Utilisez une URL HTTPS publique.
  3. Sous Événements, laissez le champ vide pour recevoir tous les événements, ou indiquez des actions et des domaines, comme member.added ou sharing.*.
  4. Choisissez Ajouter.
  5. Sous Copier le secret de signature, copiez le secret. Il ne s’affiche qu’une seule fois.

Si Dvina indique Cette adresse n’est pas accessible depuis Dvina, utilisez une URL HTTPS publique.

Vérifier la signature de chaque requête

Dvina envoie les événements par lots au format JSON et signe chaque requête. Utilisez le secret de signature pour vérifier qu’une requête provient de Dvina :

  • Chaque requête contient un en-tête X-Dvina-Signature de la forme t=<timestamp>,v1=<signature>.
  • La signature est un HMAC-SHA256 au format hexadécimal, calculé avec votre secret de signature à partir de l’horodatage, d’un point et du corps de la requête.
  • Calculez-la de votre côté et comparez les résultats. Rejetez toute requête dont la signature ne correspond pas ou dont l’horodatage est trop ancien.

Consulter ou modifier un webhook

Vos webhooks sont répertoriés sous Webhooks avec leur état : Activé, En pause ou En échec. Sélectionnez-en un pour afficher ses détails.

  • Pour le modifier, modifiez son Nom, son URL ou ses Événements, puis choisissez Enregistrer.
  • Pour le mettre en pause, désactivez Envoyer les événements. Réactivez cette option pour reprendre l’envoi.
  • Pour vérifier son fonctionnement, consultez son État et le nombre d’événements Envoyés. Un webhook en échec affiche sa Dernière erreur. Dvina continue de réessayer et consigne l’échec dans le journal d’audit.
  • Pour modifier son secret, choisissez Nouveau secret de signature…, puis confirmez. Les requêtes sont immédiatement signées avec le nouveau secret : mettez donc à jour le récepteur sans attendre.
  • Pour le supprimer, choisissez Supprimer…, puis Supprimer pour confirmer. Plus rien ne lui est envoyé.