Quando colleghi un'app di terze parti a MoveMentors tramite OAuth (il caso più comune: un assistente AI via MCP), concedi scope di autorizzazione specifici. Questo articolo elenca ogni scope e cosa fa.
Il modello degli scope
OAuth di MoveMentors segue il modello standard OAuth 2.1 con PKCE. Autorizzi un client (es. Claude), che riceve un token legato a scope specifici. Ogni richiesta del client viene validata rispetto a quegli scope.
Se concedi solo read:bookings, il client può solo leggere le prenotazioni; i tentativi di usare altri strumenti restituiscono 403 Forbidden.
Puoi concedere scope individuali durante il flusso di consenso OAuth. Puoi revocare in qualsiasi momento.
Scope di lettura
read:profile
Leggere il tuo profilo utente (nome, email, tipo di account, impostazioni).
Richiesto da quasi ogni client. Concederlo permette all'AI di sapere chi sei; senza, l'assistente non può personalizzare.
read:mentor
Leggere il tuo profilo mentor (bio, foto, location, certificazioni).
Per account mentor.
read:studio
Leggere il tuo profilo studio.
Per account studio.
read:classes
Leggere le lezioni che ospiti (titolo, calendario, capienza, prezzo, ecc.).
read:bookings
Leggere le tue prenotazioni (sia come host che come studente).
read:clients
Leggere il tuo CRM clienti (clienti che hanno prenotato, la loro storia, le tue note).
read:financials
Leggere la dashboard di guadagni e spese. Funzione Pro+.
read:reviews
Leggere le recensioni sul tuo profilo e quelle che hai lasciato.
read:messages
Leggere la tua inbox (richieste, messaggi mentor).
read:public
Cercare nella directory pubblica (mentor, studi, lezioni). Chiunque può usarla senza autenticazione, ma come scope autenticato restituisce dati leggermente arricchiti (es. distanza dalla tua location di casa salvata).
Scope di scrittura
write:profile
Aggiornare il tuo profilo utente (nome, impostazioni).
write:mentor / write:studio
Aggiornare il tuo profilo mentor o studio.
write:classes
Creare, aggiornare, eliminare le tue lezioni. Modificare calendari, capienza, prezzi.
Funzione Pro+; gli account free che concedono questo scope continuano a non poter fare modifiche (lo strumento restituisce "upgrade required").
write:bookings
Creare nuove prenotazioni (prenotare per conto di uno studente), cancellare prenotazioni, segnare come pagato.
Nota: le prenotazioni hanno vincoli. Non puoi creare una prenotazione per una lezione esaurita tramite API più di quanto tu possa via UI.
write:clients
Aggiornare note e tag dei clienti.
write:financials
Creare, aggiornare, eliminare spese. Modificare la categorizzazione dei guadagni. Funzione Pro+.
write:reviews
Rispondere alle recensioni sul tuo profilo.
write:messages
Inviare messaggi (richieste, risposte, outreach mentor).
Scope speciali
mcp:tools
Consente al client di chiamare strumenti MCP. Richiesto per i server MCP; senza, l'endpoint MCP rifiuta le richieste.
offline_access
Consente al client di rinnovare il proprio access token senza che tu debba ri-autorizzare. Scope OAuth standard; se non concesso, il client deve ri-autenticarsi ogni volta che il token scade (circa 1 ora).
La maggior parte dei client lo richiede così l'utente non deve ri-autenticarsi continuamente.
Bundle di scope comuni
La maggior parte dei client chiede un bundle sensato piuttosto che ogni singolo scope. Bundle tipici:
- Sola lettura:
read:profile,read:bookings,read:classes,read:clients. Utile per casi d'uso tipo "mostrami il mio calendario". - Assistente personale: sola lettura più
write:bookings,write:classes,write:messages. L'assistente può gestire le tue operazioni. - Controllo completo: tutto tranne
write:financials. Per power user.
Puoi negare scope specifici durante la schermata di consenso; il client si adatta (alcuni strumenti saranno non disponibili, ma il resto funziona).
Cosa posso fare durante il consenso
La schermata di consenso OAuth mostra:
- Il nome del client (es. "Claude Desktop").
- Il sito web del client (se fornito).
- Ogni scope richiesto dal client.
- Una casella per scope (alcuni sono pre-spuntati come obbligatori).
Puoi:
- Approvare tutto (l'opzione predefinita facile).
- Deselezionare scope specifici e approvare il sottoinsieme.
- Negare completamente.
Revocare l'accesso
/settings/connected-apps mostra ogni client OAuth collegato al tuo account. Per ciascuno vedi:
- Il nome del client.
- Quando è stato autorizzato.
- Quali scope ha.
- Timestamp dell'ultimo utilizzo.
- Un pulsante "Revoca".
Clicca revoca e il token viene invalidato. Il client perde immediatamente l'accesso. Se ri-autorizzi lo stesso client in seguito, riparti da zero; nessuno scope "ricordato".
Audit logging
Ogni richiesta OAuth viene registrata nel tuo audit log su /settings/audit-log. Visibile:
- Quale client ha fatto la richiesta.
- Quale strumento è stato chiamato.
- Gli argomenti (con i valori sensibili oscurati).
- Lo stato della risposta.
Utile quando vuoi sapere cosa ha fatto un assistente AI per tuo conto.
Cosa gli scope non coprono
Alcune cose che gli scope specificamente NON permettono, indipendentemente dalla concessione:
- Leggere dati privati di altri utenti. Anche con tutti gli scope, un client può accedere solo ai TUOI dati e ai dati pubblici altrui.
- Avviare payout o modificare impostazioni lato Stripe. Quelle sono su Stripe, non da noi.
- Modificare impostazioni account che richiedono conferma via email (cambiare la tua email, ecc.).
Queste sono intenzionali. Alcune azioni sono troppo critiche per essere delegate.
Domande frequenti
Un client può richiedere uno scope che non ho concesso? Il client otterrà 403 su qualsiasi strumento che richiede uno scope non concesso. Non può fare escalation.
Posso vedere cosa stava facendo un vecchio client se l'ho revocato? Sì. L'audit log conserva le richieste passate anche da client che sono stati revocati.
Possono più client collegarsi con scope sovrapposti? Sì. Ogni client collegato ha il proprio token. Puoi avere Claude con accesso completo E ChatGPT in sola lettura.
C'è un modo di limitare per lezione o per cliente (più granulare degli scope)? Al momento no. Gli scope sono il confine; non supportiamo "leggi prenotazioni solo per la lezione X" o ACL granulari simili. Potremmo aggiungerli se c'è richiesta.
Perché non c'è uno scope delete:account?
L'eliminazione dell'account richiede conferma via email. Non può essere fatta tramite OAuth, anche con scope completi.
Prossimi passi
- Server MCP: il principale consumatore di OAuth.
- App connesse: gestisci le tue autorizzazioni.