Authentification
L'identifiant attendu par chaque interface Nudge, des endpoints publics ouverts à OAuth pour le serveur MCP.
En résumé
| Interface | Identifiant | Provenance |
|---|---|---|
| Endpoints publics des formulaires | Aucun | — |
API de réservation IA, lectures et book | Aucun | — |
API de réservation IA, cancel, reschedule et get_booking_status | Jeton du rendez-vous (token) | Le cancel_url renvoyé à la réservation |
Gestion d'un rendez-vous (/api/booking/{bookingId}/…) | Jeton du rendez-vous | Les liens de l'e-mail de confirmation, ou cancel_url |
| Serveur MCP | Jeton d'accès OAuth 2.1 (scope mcp:manage), ou jeton de session | Votre compte Nudge |
| Webhooks que vous recevez | Signature à vérifier (X-Nudge-Signature) | Le secret de signature défini sur le webhook |
Endpoints publics : sans clé, limités par IP
L'API de réservation IA et les endpoints publics des formulaires fonctionnent sans identifiant. C'est voulu : ils servent les mêmes informations que vos pages de réservation publiques, et l'API de réservation IA est faite pour être appelée par des agents que vous ne maîtrisez pas.
Ce qui les protège :
- Des limites de débit par adresse IP sur chaque endpoint (voir Limites de débit).
- Des créneaux signés. Un créneau renvoyé par l'API de réservation IA porte une signature HMAC et expire au bout de 30 minutes. Un appelant ne peut inventer ni un horaire ni un hôte : seul un créneau proposé par Nudge peut être réservé.
- Un interrupteur par formulaire. Désactivez Activer la réservation IA dans la section Réservation IA des réglages du formulaire : le formulaire refuse alors l'API de réservation IA (
403). - Pas d'abonnement, pas de réservation. Pour un espace sans abonnement actif, l'API de réservation IA répond comme si le formulaire n'existait pas.
Jeton du rendez-vous
Chaque rendez-vous possède un jeton de gestion secret. C'est lui qui prouve que l'appelant est bien la personne qui a réservé ; il est exigé pour annuler, déplacer ou lire le statut d'un rendez-vous.
- Quand un agent réserve via l'API de réservation IA, la réponse contient
cancel_url:https://app.asknudge.ai/booking/{bookingId}/cancel?token={token}. La valeur du paramètretokenest le jeton du rendez-vous. Conservez-la avec l'identifiant du rendez-vous. - L'e-mail de confirmation envoyé au contact porte la même capacité dans ses liens « déplacer » et « annuler ».
Envoyez le jeton dans le corps JSON ("token": "…") ou en paramètre de requête ?token=. Nudge le compare en temps constant et répond de la même façon à « rendez-vous inconnu » et à « mauvais jeton » : un appelant ne peut pas sonder les identifiants.
Traitez le jeton du rendez-vous comme un mot de passe : quiconque le détient peut annuler ou déplacer le rendez-vous. Ne l'écrivez ni dans vos logs ni dans vos outils d'analyse.
Serveur MCP : OAuth avec votre compte Nudge
Le serveur MCP https://mcp.asknudge.ai est protégé par OAuth 2.1. Vous ne copiez aucune clé : votre client MCP ouvre une fenêtre de connexion Nudge, vous autorisez l'accès et le client reçoit un jeton.
| Élément | Valeur |
|---|---|
| Ressource protégée | https://mcp.asknudge.ai |
| Découverte | https://mcp.asknudge.ai/.well-known/oauth-protected-resource, puis les métadonnées du serveur d'autorisation sur https://app.asknudge.ai |
| Scopes | mcp:manage (obligatoire), offline_access (jetons de rafraîchissement), plus openid, profile, email |
| Enregistrement du client | Enregistrement dynamique et documents de métadonnées client pris en charge : la plupart des clients s'enregistrent seuls |
| PKCE | Pris en charge |
Une requête non authentifiée reçoit un 401 avec un en-tête WWW-Authenticate qui pointe vers le document de découverte : c'est ainsi que Claude et ChatGPT trouvent seuls le parcours de connexion.
Sur l'écran de consentement, Nudge nomme le client qui demande l'accès et indique qu'il pourra consulter, créer, modifier et supprimer des données, gérer les accès et la facturation, avec vos droits actuels. Cliquez sur Autoriser pour accepter ou sur Refuser pour décliner.
Chaque appel d'outil s'exécute ensuite en votre nom : même appartenance aux espaces, même rôle, mêmes contrôles de permissions que dans l'application. Si votre rôle ne peut pas annuler un rendez-vous dans l'application, l'assistant ne le peut pas non plus. Révoquer votre session ou perdre l'accès à un espace retire aussi l'accès de l'assistant.
Pour les clients qui ne savent pas faire d'OAuth, voir Se connecter avec un jeton de session.
Webhooks : vérifiez la signature
Les webhooks vont dans l'autre sens : c'est Nudge qui appelle votre URL. Vous authentifiez Nudge en vérifiant l'en-tête X-Nudge-Signature avec le secret de signature défini à la création du webhook. Voir Vérifier la signature.