OAuth voor partner-apps
Een partner-app, een automatiseringstool of een eigen app die voor een MonoChat-gebruiker werkt, kan de custom-function-API (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) aanroepen met een OAuth-toegangstoken in plaats van een API-token. De gebruiker keurt de app goed op een MonoChat-pagina, kiest de organisaties die de app mag bereiken en kan de app op elk moment intrekken onder Gekoppelde apps in de profielinstellingen.
API-tokens blijven werken op hetzelfde endpoint. OAuth is de optie voor een app die namens anderen handelt: de app ziet nooit een wachtwoord of API-token, en elke gebruiker kan de app zelf afsluiten.
Een aanroep met een toegangstoken draait als de gebruiker die de app heeft goedgekeurd, met diens rollen. Hij voert alleen de aangepaste methoden van de organisatie uit, en alleen in organisaties waar de gebruiker agent is.
Een client krijgen
Vraag MonoChat om een client voor uw app. MonoChat registreert die met:
- de naam van de app, die de goedkeuringspagina en Gekoppelde apps tonen;
- de redirect-URI's, exact vergeleken:
https-adressen, ofhttpoplocalhost,127.0.0.1of[::1](elke poort); - de scopes die de app mag vragen:
custom-functions:runvoor deze API.
U krijgt een client-ID (begint met monochat_rc_) en een clientgeheim (begint met monochat_cs_). Het geheim wordt één keer getoond; MonoChat bewaart alleen de hash. Bewaar het op uw server, nooit in een browser of mobiele app.
Een app die geen geheim kan bewaren, zoals een app in de browser of op de computer van de gebruiker, kan in plaats daarvan, net als MCP-clients, de URL van een client-ID-metadatadocument als client-ID gebruiken. Die app stuurt dan geen geheim.
Endpoints
De metadata van de autorisatieserver op https://app.monochat.ai/.well-known/oauth-authorization-server noemen elk endpoint. Op een white-label- of zelf gehoste installatie gebruikt u het eigen adres van die installatie.
| Instelling | Waarde |
|---|---|
| Autorisatie-endpoint | https://app.monochat.ai/oauth/authorize |
| Token-endpoint | https://app.monochat.ai/oauth/token |
| Intrekkings-endpoint | https://app.monochat.ai/oauth/revoke |
| Resource | https://app.monochat.ai/api/custom-functions |
| Scope | custom-functions:run |
| Clientauthenticatie | HTTP Basic, of client_id en client_secret in de request-body |
De metadata van de resource zelf staan op https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.
Een gebruiker koppelen
MonoChat gebruikt de authorization-code-flow met PKCE (S256). De gebruiker moet verificatie in twee stappen (via e-mail of een authenticator-app) hebben ingesteld.
- Stuur de gebruiker naar het autorisatie-endpoint met
response_type=code, uwclient_id, een geregistreerderedirect_uri,scope=custom-functions:run,resource=https://app.monochat.ai/api/custom-functions, eenstateen eencode_challengemetcode_challenge_method=S256. - De gebruiker meldt zich zo nodig aan bij MonoChat. De goedkeuringspagina noemt uw app en toont Aangepaste methoden namens u uitvoeren. De gebruiker kan de Organisaties kiezen die de app mag bereiken (al de zijne als hij er geen kiest), voert de 6-cijferige bevestigingscode in en klikt op Toestaan.
- MonoChat stuurt de gebruiker terug naar uw
redirect_urimetcode,stateeniss. Klikt de gebruiker op Weigeren, dan stuurt het in plaats daarvanerror=access_denied. - Wissel de code binnen 5 minuten in bij het token-endpoint:
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>
Het antwoord bevat een access_token (begint met monochat_at_) dat expires_in seconden (een uur) geldig is, een refresh_token (begint met monochat_rt_) en de toegekende scope.
De API aanroepen
Stuur het toegangstoken mee 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 | Wanneer |
|---|---|
401 | Het token is onbekend, verlopen of ingetrokken, of het is uitgegeven voor een andere resource, zoals de MCP-server. De header WWW-Authenticate verwijst naar de resource-metadata. |
403 | De organisatie hoort niet bij de organisaties die de gebruiker voor de app heeft toegestaan, de gebruiker heeft geen toegang tot de organisatie, of de grant bevat custom-functions:run niet. |
429 | Er is een limiet bereikt; wacht het aantal seconden uit Retry-After. Aanroepen worden per minuut geteld: 120 per grant en 1.200 per client, naast de eigen limiet van de organisatie voor dit endpoint. |
Vernieuwen en intrekken
- Vernieuwen: roep vóór het verlopen van het toegangstoken het token-endpoint aan met
grant_type=refresh_tokenen hetrefresh_token. Elke vernieuwing geeft een nieuw refreshtoken; gebruik het nieuwe. Een refreshtoken dat meer dan een minuut na vervanging opnieuw wordt gebruikt, beëindigt de grant. - Verloop: de grant eindigt 90 dagen na de laatste vernieuwing, wanneer de gebruiker hem intrekt onder Gekoppelde apps, of wanneer de gebruiker zijn wachtwoord wijzigt of herstelt. De gebruiker moet de app dan opnieuw goedkeuren.
- Intrekken: om een gebruiker los te koppelen, stuurt u het toegangs- of refreshtoken met uw clientauthenticatie naar het intrekkings-endpoint:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>
Als u dezelfde gebruiker opnieuw aan uw app koppelt, vervangt dat zijn eerdere grant.