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.
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 oderhttpauflocalhost,127.0.0.1oder[::1](beliebiger Port); - den Scopes, die sie anfordern darf:
custom-functions:runfü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.
| Einstellung | Wert |
|---|---|
| Autorisierungsendpunkt | https://app.monochat.ai/oauth/authorize |
| Token-Endpunkt | https://app.monochat.ai/oauth/token |
| Widerrufsendpunkt | https://app.monochat.ai/oauth/revoke |
| Ressource | https://app.monochat.ai/api/custom-functions |
| Scope | custom-functions:run |
| Client-Authentifizierung | HTTP 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.
- Leiten Sie den Benutzer zum Autorisierungsendpunkt mit
response_type=code, Ihrerclient_id, einer registriertenredirect_uri,scope=custom-functions:run,resource=https://app.monochat.ai/api/custom-functions, einemstateund einercode_challengemitcode_challenge_method=S256. - 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.
- MonoChat leitet den Benutzer mit
code,stateundisszu Ihrerredirect_urizurück. Klickt der Benutzer auf Ablehnen, sendet es stattdessenerror=access_denied. - 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 '{}'
| Status | Wann |
|---|---|
401 | Das 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. |
403 | Die 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. |
429 | Ein 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_tokenund demrefresh_tokenauf. 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.