OAuth per le app dei partner
Un'app partner, uno strumento di automazione o un'app personalizzata che lavora per un utente MonoChat può chiamare l'API delle funzioni personalizzate (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) con un token di accesso OAuth invece di un token API. L'utente approva l'app su una pagina MonoChat, sceglie le organizzazioni che può raggiungere e può revocarla in qualsiasi momento in App collegate nelle sue impostazioni del profilo.
I token API continuano a funzionare sullo stesso endpoint. OAuth è l'opzione per un'app che agisce per altre persone: non vede mai una password o un token API, e ogni utente può scollegarla da solo.
Una chiamata fatta con un token di accesso viene eseguita come l'utente che ha approvato l'app, con i suoi ruoli. Esegue solo i metodi personalizzati dell'organizzazione, e solo nelle organizzazioni in cui l'utente è un agente.
Ottenere un client
Chiedi a MonoChat un client per la tua app. MonoChat lo registra con:
- il nome dell'app, mostrato dalla pagina di approvazione e da App collegate;
- i suoi URI di reindirizzamento, con corrispondenza esatta: indirizzi
https, oppurehttpsulocalhost,127.0.0.1o[::1](qualsiasi porta); - gli scope che può richiedere:
custom-functions:runper questa API.
Ricevi un ID client (inizia con monochat_rc_) e un secret del client (inizia con monochat_cs_). Il secret viene mostrato una sola volta; MonoChat ne conserva solo l'hash. Tienilo sul tuo server, mai in un browser o in un'app mobile.
Un'app che non può custodire un secret, come una che gira nel browser o sul computer dell'utente, può usare invece come ID client l'URL di un documento di metadati del client, come fanno i client MCP. In questo caso non invia alcun secret.
Endpoint
I metadati del server di autorizzazione all'indirizzo https://app.monochat.ai/.well-known/oauth-authorization-server elencano tutti gli endpoint. Su un'installazione white label o self-hosted, usa l'indirizzo di quell'installazione.
| Impostazione | Valore |
|---|---|
| Endpoint di autorizzazione | https://app.monochat.ai/oauth/authorize |
| Endpoint del token | https://app.monochat.ai/oauth/token |
| Endpoint di revoca | https://app.monochat.ai/oauth/revoke |
| Risorsa | https://app.monochat.ai/api/custom-functions |
| Scope | custom-functions:run |
| Autenticazione del client | HTTP Basic, oppure client_id e client_secret nel corpo della richiesta |
I metadati della risorsa stessa si trovano in https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.
Collegare un utente
MonoChat usa il flusso con codice di autorizzazione e PKCE (S256). L'utente deve aver configurato la verifica in due passaggi (via e-mail o con un'app di autenticazione).
- Invia l'utente all'endpoint di autorizzazione con
response_type=code, il tuoclient_id, unredirect_uriregistrato,scope=custom-functions:run,resource=https://app.monochat.ai/api/custom-functions, unostatee uncode_challengeconcode_challenge_method=S256. - Se necessario l'utente accede a MonoChat. La pagina di approvazione nomina la tua app e mostra Eseguire metodi personalizzati per tuo conto. L'utente può scegliere le Organizzazioni che l'app può raggiungere (tutte le sue se non ne sceglie nessuna), inserisce il codice di conferma a 6 cifre e fa clic su Consenti.
- MonoChat rimanda l'utente al tuo
redirect_uriconcode,stateeiss. Se l'utente fa clic su Rifiuta, invia inveceerror=access_denied. - Scambia il codice sull'endpoint del token entro 5 minuti:
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 risposta contiene un access_token (inizia con monochat_at_) valido per expires_in secondi (un'ora), un refresh_token (inizia con monochat_rt_) e lo scope concesso.
Chiamare l'API
Invia il token di accesso come 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 '{}'
| Stato | Quando |
|---|---|
401 | Il token è sconosciuto, scaduto o revocato, oppure è stato emesso per un'altra risorsa, come il server MCP. L'header WWW-Authenticate indica i metadati della risorsa. |
403 | L'organizzazione non è tra quelle che l'utente ha consentito all'app, l'utente non ha accesso all'organizzazione, oppure la concessione non include custom-functions:run. |
429 | È stato raggiunto un limite; attendi i secondi indicati in Retry-After. Le chiamate sono contate al minuto: 120 per concessione e 1.200 per client, oltre al limite dell'organizzazione per questo endpoint. |
Rinnovare e revocare
- Rinnovo: prima che il token di accesso scada, chiama l'endpoint del token con
grant_type=refresh_tokene ilrefresh_token. Ogni rinnovo restituisce un nuovo refresh token; usa quello nuovo. Un refresh token usato di nuovo più di un minuto dopo essere stato sostituito chiude la concessione. - Scadenza: la concessione termina 90 giorni dopo l'ultimo rinnovo, quando l'utente la revoca in App collegate, o quando l'utente cambia o reimposta la password. L'utente deve quindi approvare di nuovo l'app.
- Revoca: per scollegare un utente, invia il token di accesso o il refresh token all'endpoint di revoca con l'autenticazione del tuo client:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>
Collegare di nuovo lo stesso utente alla tua app sostituisce la sua concessione precedente.