Aller au contenu principal

OAuth pour les apps partenaires

Une app partenaire, un outil d'automatisation ou une app personnalisée qui travaille pour un utilisateur MonoChat peut appeler l'API des fonctions personnalisées (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) avec un jeton d'accès OAuth au lieu d'un jeton API. L'utilisateur approuve l'app sur une page MonoChat, choisit les organisations qu'elle peut atteindre et peut la révoquer à tout moment sous Apps connectées dans ses paramètres de profil.

Les jetons API continuent de fonctionner sur le même endpoint. OAuth est l'option pour une app qui agit pour d'autres personnes : elle ne voit jamais de mot de passe ni de jeton API, et chaque utilisateur peut la couper lui-même.

L'app agit en tant qu'utilisateur

Un appel fait avec un jeton d'accès s'exécute en tant que l'utilisateur qui a approuvé l'app, avec ses rôles. Il n'exécute que les méthodes personnalisées de l'organisation, et seulement dans les organisations où l'utilisateur est agent.

Obtenir un client​

Demandez à MonoChat un client pour votre app. MonoChat l'enregistre avec :

  • le nom de l'app, que la page d'approbation et Apps connectées affichent ;
  • ses URI de redirection, comparées à l'identique : des adresses https, ou http sur localhost, 127.0.0.1 ou [::1] (tout port) ;
  • les scopes qu'elle peut demander : custom-functions:run pour cette API.

Vous recevez un ID client (il commence par monochat_rc_) et un secret client (il commence par monochat_cs_). Le secret n'est affiché qu'une fois ; MonoChat n'en garde que l'empreinte. Conservez-le sur votre serveur, jamais dans un navigateur ou une app mobile.

Une app qui ne peut pas garder un secret, par exemple une app qui tourne dans le navigateur ou sur l'ordinateur de l'utilisateur, peut utiliser à la place l'URL d'un document de métadonnées client comme ID client, comme le font les clients MCP. Elle n'envoie alors aucun secret.

Endpoints​

Les métadonnées du serveur d'autorisation à l'adresse https://app.monochat.ai/.well-known/oauth-authorization-server listent tous les endpoints. Sur une installation en marque blanche ou auto-hébergée, utilisez l'adresse propre à cette installation.

ParamètreValeur
Endpoint d'autorisationhttps://app.monochat.ai/oauth/authorize
Endpoint de jetonhttps://app.monochat.ai/oauth/token
Endpoint de révocationhttps://app.monochat.ai/oauth/revoke
Ressourcehttps://app.monochat.ai/api/custom-functions
Scopecustom-functions:run
Authentification du clientHTTP Basic, ou client_id et client_secret dans le corps de la requête

Les métadonnées propres à la ressource se trouvent à https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.

Connecter un utilisateur​

MonoChat utilise le flux du code d'autorisation avec PKCE (S256). L'utilisateur doit avoir configuré la vérification en deux étapes (par e-mail ou par une app d'authentification).

  1. Envoyez l'utilisateur vers l'endpoint d'autorisation avec response_type=code, votre client_id, une redirect_uri enregistrée, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, un state et un code_challenge avec code_challenge_method=S256.
  2. L'utilisateur se connecte à MonoChat si nécessaire. La page d'approbation nomme votre app et affiche Exécuter des méthodes personnalisées en votre nom. L'utilisateur peut choisir les Organisations que l'app peut atteindre (toutes les siennes si aucune n'est choisie), saisit son code de confirmation à 6 chiffres et clique sur Autoriser.
  3. MonoChat renvoie l'utilisateur vers votre redirect_uri avec code, state et iss. Si l'utilisateur clique sur Refuser, il envoie error=access_denied à la place.
  4. Échangez le code sur l'endpoint de jeton dans les 5 minutes :
curl -X POST https://app.monochat.ai/oauth/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=<redirect_uri> \
-d code_verifier=<code_verifier>

La réponse contient un access_token (il commence par monochat_at_) valable expires_in secondes (une heure), un refresh_token (il commence par monochat_rt_) et le scope accordé.

Appeler l'API​

Envoyez le jeton d'accès comme jeton bearer :

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
StatutQuand
401Le jeton est inconnu, expiré ou révoqué, ou il a été émis pour une autre ressource, comme le serveur MCP. L'en-tête WWW-Authenticate indique les métadonnées de la ressource.
403L'organisation ne fait pas partie de celles que l'utilisateur a autorisées pour l'app, l'utilisateur n'a pas accès à l'organisation, ou l'autorisation ne contient pas custom-functions:run.
429Une limite est atteinte ; attendez le nombre de secondes indiqué dans Retry-After. Les appels sont comptés par minute : 120 par autorisation et 1 200 par client, en plus de la limite propre à l'organisation pour cet endpoint.

Rafraîchir et révoquer​

  • Rafraîchir : avant l'expiration du jeton d'accès, appelez l'endpoint de jeton avec grant_type=refresh_token et le refresh_token. Chaque rafraîchissement renvoie un nouveau jeton de rafraîchissement ; utilisez le nouveau. Un jeton de rafraîchissement réutilisé plus d'une minute après avoir été remplacé met fin à l'autorisation.
  • Expiration : l'autorisation prend fin 90 jours après son dernier rafraîchissement, quand l'utilisateur la révoque sous Apps connectées, ou quand l'utilisateur change ou réinitialise son mot de passe. L'utilisateur doit alors approuver l'app à nouveau.
  • Révoquer : pour déconnecter un utilisateur, envoyez le jeton d'accès ou de rafraîchissement à l'endpoint de révocation avec l'authentification de votre client :
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

Reconnecter le même utilisateur à votre app remplace son autorisation précédente.