Treceți la conținutul principal

OAuth pentru aplicațiile partenerilor

O aplicație parteneră, un instrument de automatizare sau o aplicație personalizată care lucrează pentru un utilizator MonoChat poate apela API-ul de funcții personalizate (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) cu un token de acces OAuth în loc de un token API. Utilizatorul aprobă aplicația pe o pagină MonoChat, alege organizațiile la care poate ajunge și o poate revoca oricând din Aplicații conectate, în setările profilului.

Tokenurile API funcționează în continuare pe același endpoint. OAuth este opțiunea pentru o aplicație care acționează pentru alte persoane: nu vede niciodată o parolă sau un token API, iar fiecare utilizator o poate deconecta singur.

Aplicația acționează ca utilizatorul

Un apel făcut cu un token de acces rulează ca utilizatorul care a aprobat aplicația, cu rolurile lui. Rulează doar metodele personalizate ale organizației și doar în organizațiile în care utilizatorul este agent.

Obține un client​

Cere MonoChat un client pentru aplicația ta. MonoChat îl înregistrează cu:

  • numele aplicației, afișat pe pagina de aprobare și în Aplicații conectate;
  • URI-urile ei de redirecționare, potrivite exact: adrese https sau http pe localhost, 127.0.0.1 ori [::1] (orice port);
  • scope-urile pe care le poate cere: custom-functions:run pentru acest API.

Primești un ID client (începe cu monochat_rc_) și un secret client (începe cu monochat_cs_). Secretul este afișat o singură dată; MonoChat păstrează doar hash-ul lui. Păstrează-l pe serverul tău, niciodată într-un browser sau într-o aplicație mobilă.

O aplicație care nu poate păstra un secret, de exemplu una care rulează în browser sau pe computerul utilizatorului, poate folosi în schimb ca ID client URL-ul unui document de metadate al clientului, așa cum fac clienții MCP. Atunci nu trimite niciun secret.

Endpointuri​

Metadatele serverului de autorizare de la https://app.monochat.ai/.well-known/oauth-authorization-server listează toate endpointurile. Pe o instalare white label sau găzduită de tine, folosește adresa proprie a acelei instalări.

SetareValoare
Endpoint de autorizarehttps://app.monochat.ai/oauth/authorize
Endpoint de tokenhttps://app.monochat.ai/oauth/token
Endpoint de revocarehttps://app.monochat.ai/oauth/revoke
Resursăhttps://app.monochat.ai/api/custom-functions
Scopecustom-functions:run
Autentificarea clientuluiHTTP Basic sau client_id și client_secret în corpul cererii

Metadatele resursei înseși se află la https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.

Conectează un utilizator​

MonoChat folosește fluxul cu cod de autorizare și PKCE (S256). Utilizatorul trebuie să aibă configurată verificarea în doi pași (prin e-mail sau cu o aplicație de autentificare).

  1. Trimite utilizatorul la endpointul de autorizare cu response_type=code, client_id-ul tău, un redirect_uri înregistrat, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, un state și un code_challenge cu code_challenge_method=S256.
  2. Utilizatorul se conectează la MonoChat dacă e nevoie. Pagina de aprobare numește aplicația ta și arată Rulează metode personalizate în numele tău. Utilizatorul poate alege Organizații la care poate ajunge aplicația (toate ale lui dacă nu alege niciuna), introduce codul de confirmare din 6 cifre și dă clic pe Permite.
  3. MonoChat trimite utilizatorul înapoi la redirect_uri-ul tău cu code, state și iss. Dacă utilizatorul dă clic pe Refuză, trimite în schimb error=access_denied.
  4. Schimbă codul la endpointul de token în cel mult 5 minute:
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>

Răspunsul conține un access_token (începe cu monochat_at_) valabil expires_in secunde (o oră), un refresh_token (începe cu monochat_rt_) și scope-ul acordat.

Apelează API-ul​

Trimite tokenul de acces ca token bearer:

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
StareCând
401Tokenul este necunoscut, expirat sau revocat ori a fost emis pentru altă resursă, cum ar fi serverul MCP. Antetul WWW-Authenticate indică metadatele resursei.
403Organizația nu se numără printre cele permise de utilizator pentru aplicație, utilizatorul nu are acces la organizație sau permisiunea nu include custom-functions:run.
429A fost atinsă o limită; așteaptă numărul de secunde din Retry-After. Apelurile se numără pe minut: 120 pe permisiune și 1.200 pe client, pe lângă limita proprie a organizației pentru acest endpoint.

Reînnoire și revocare​

  • Reînnoire: înainte să expire tokenul de acces, apelează endpointul de token cu grant_type=refresh_token și refresh_token. Fiecare reînnoire întoarce un nou refresh token; folosește-l pe cel nou. Un refresh token folosit din nou la mai mult de un minut după ce a fost înlocuit încheie permisiunea.
  • Expirare: permisiunea se încheie la 90 de zile după ultima reînnoire, când utilizatorul o revocă din Aplicații conectate sau când utilizatorul își schimbă ori își resetează parola. Utilizatorul trebuie apoi să aprobe din nou aplicația.
  • Revocare: pentru a deconecta un utilizator, trimite tokenul de acces sau refresh tokenul la endpointul de revocare, cu autentificarea clientului tău:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

Conectarea din nou a aceluiași utilizator la aplicația ta înlocuiește permisiunea lui anterioară.