Zum Hauptinhalt springen

OAuth für Partner-Apps

Eine Partner-App, ein Automatisierungstool oder eine eigene App, die für einen MonoChat-Benutzer arbeitet, kann die Custom-Function-API (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) mit einem OAuth-Zugriffstoken statt mit einem API-Token aufrufen. Der Benutzer genehmigt die App auf einer MonoChat-Seite, wählt die Organisationen, die sie erreichen darf, und kann sie jederzeit unter Verbundene Apps in seinen Profileinstellungen widerrufen.

API-Token funktionieren am selben Endpunkt weiter. OAuth ist die Option für eine App, die für andere Personen handelt: Sie sieht nie ein Passwort oder ein API-Token, und jeder Benutzer kann sie selbst trennen.

Die App handelt als der Benutzer

Ein Aufruf mit einem Zugriffstoken läuft als der Benutzer, der die App genehmigt hat, mit dessen Rollen. Er führt nur die benutzerdefinierten Methoden der Organisation aus, und nur in Organisationen, in denen der Benutzer Agent ist.

Einen Client erhalten​

Fragen Sie MonoChat nach einem Client für Ihre App. MonoChat registriert ihn mit:

  • dem Namen der App, den die Genehmigungsseite und Verbundene Apps anzeigen;
  • ihren Weiterleitungs-URIs, exakt abgeglichen: https-Adressen oder http auf localhost, 127.0.0.1 oder [::1] (beliebiger Port);
  • den Scopes, die sie anfordern darf: custom-functions:run für diese API.

Sie erhalten eine Client-ID (beginnt mit monochat_rc_) und ein Client-Secret (beginnt mit monochat_cs_). Das Secret wird nur einmal angezeigt; MonoChat speichert nur seinen Hash. Bewahren Sie es auf Ihrem Server auf, nie in einem Browser oder einer mobilen App.

Eine App, die kein Secret geheim halten kann, etwa eine im Browser oder auf dem Computer des Benutzers, kann stattdessen wie MCP-Clients die URL eines Client-ID-Metadatendokuments als Client-ID verwenden. Sie sendet dann kein Secret.

Endpunkte​

Die Metadaten des Autorisierungsservers unter https://app.monochat.ai/.well-known/oauth-authorization-server listen alle Endpunkte. Auf einer White-Label- oder selbst gehosteten Installation verwenden Sie deren eigene Adresse.

EinstellungWert
Autorisierungsendpunkthttps://app.monochat.ai/oauth/authorize
Token-Endpunkthttps://app.monochat.ai/oauth/token
Widerrufsendpunkthttps://app.monochat.ai/oauth/revoke
Ressourcehttps://app.monochat.ai/api/custom-functions
Scopecustom-functions:run
Client-AuthentifizierungHTTP Basic oder client_id und client_secret im Request-Body

Die Metadaten der Ressource selbst liegen unter https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.

Einen Benutzer verbinden​

MonoChat verwendet den Authorization-Code-Flow mit PKCE (S256). Der Benutzer muss die Bestätigung in zwei Schritten (per E-Mail oder Authenticator-App) eingerichtet haben.

  1. Leiten Sie den Benutzer zum Autorisierungsendpunkt mit response_type=code, Ihrer client_id, einer registrierten redirect_uri, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, einem state und einer code_challenge mit code_challenge_method=S256.
  2. Der Benutzer meldet sich bei Bedarf bei MonoChat an. Die Genehmigungsseite nennt Ihre App und zeigt Benutzerdefinierte Methoden in Ihrem Namen ausführen. Der Benutzer kann die Organisationen wählen, die die App erreichen darf (alle seine, wenn keine gewählt ist), gibt seinen 6-stelligen Bestätigungscode ein und klickt auf Erlauben.
  3. MonoChat leitet den Benutzer mit code, state und iss zu Ihrer redirect_uri zurück. Klickt der Benutzer auf Ablehnen, sendet es stattdessen error=access_denied.
  4. Tauschen Sie den Code innerhalb von 5 Minuten am Token-Endpunkt ein:
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>

Die Antwort enthält ein access_token (beginnt mit monochat_at_), das expires_in Sekunden (eine Stunde) gilt, ein refresh_token (beginnt mit monochat_rt_) und den gewährten scope.

Die API aufrufen​

Senden Sie das Zugriffstoken als Bearer-Token:

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
StatusWann
401Das Token ist unbekannt, abgelaufen oder widerrufen, oder es wurde für eine andere Ressource ausgestellt, etwa den MCP-Server. Der Header WWW-Authenticate verweist auf die Ressourcen-Metadaten.
403Die Organisation gehört nicht zu denen, die der Benutzer für die App erlaubt hat, der Benutzer hat keinen Zugriff auf die Organisation, oder der Grant enthält custom-functions:run nicht.
429Ein Limit ist erreicht; warten Sie die Sekunden aus Retry-After. Aufrufe werden pro Minute gezählt: 120 pro Grant und 1.200 pro Client, zusätzlich zum eigenen Limit der Organisation für diesen Endpunkt.

Erneuern und widerrufen​

  • Erneuern: Rufen Sie vor Ablauf des Zugriffstokens den Token-Endpunkt mit grant_type=refresh_token und dem refresh_token auf. Jede Erneuerung liefert ein neues Refresh-Token; verwenden Sie das neue. Ein Refresh-Token, das mehr als eine Minute nach seiner Ablösung erneut verwendet wird, beendet den Grant.
  • Ablauf: Der Grant endet 90 Tage nach seiner letzten Erneuerung, wenn der Benutzer ihn unter Verbundene Apps widerruft oder wenn der Benutzer sein Passwort ändert oder zurücksetzt. Der Benutzer muss die App dann erneut genehmigen.
  • Widerrufen: Um einen Benutzer zu trennen, senden Sie das Zugriffs- oder Refresh-Token mit Ihrer Client-Authentifizierung an den Widerrufsendpunkt:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

Wenn Sie denselben Benutzer erneut mit Ihrer App verbinden, ersetzt das seinen früheren Grant.