Passa al contenuto principale

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.

L'app agisce come l'utente

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, oppure http su localhost, 127.0.0.1 o [::1] (qualsiasi porta);
  • gli scope che può richiedere: custom-functions:run per 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.

ImpostazioneValore
Endpoint di autorizzazionehttps://app.monochat.ai/oauth/authorize
Endpoint del tokenhttps://app.monochat.ai/oauth/token
Endpoint di revocahttps://app.monochat.ai/oauth/revoke
Risorsahttps://app.monochat.ai/api/custom-functions
Scopecustom-functions:run
Autenticazione del clientHTTP 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).

  1. Invia l'utente all'endpoint di autorizzazione con response_type=code, il tuo client_id, un redirect_uri registrato, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, uno state e un code_challenge con code_challenge_method=S256.
  2. 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.
  3. MonoChat rimanda l'utente al tuo redirect_uri con code, state e iss. Se l'utente fa clic su Rifiuta, invia invece error=access_denied.
  4. 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 '{}'
StatoQuando
401Il 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.
403L'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_token e il refresh_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.