OAuth 2.1
Lascia che altre app facciano accedere i propri utenti con un account Bot-Hosting, come Accedi con Discord. Basato su OAuth 2.1 e PKCE, quindi funziona con qualsiasi client OAuth standard.
Usa una chiave API per gestire il tuo account. Usa OAuth quando crei un'app che agisce sugli account di altre persone, così accedono e danno il consenso invece di incollare una chiave. Gli assistenti AI come ChatGPT si collegano esattamente con questo flusso.
Il flusso
- 01 Crea un'app Registra un nome e un URI di reindirizzamento nelle impostazioni sviluppatore. Ottieni un client_id pubblico, senza segreto.
- 02 Manda gli utenti ad autorizzare Reindirizza a /oauth/authorize con PKCE. L'utente accede e approva gli scope.
- 03 Scambia il codice Tornano con un codice. Invialo con POST all'endpoint dei token per ottenere un token di accesso.
- 04 Chiama l'API per loro conto Invia il token come Bearer a /api/v1 e aggiornalo in background.
Endpoint
| Endpoint | Scopo |
|---|---|
| GET /oauth/authorize | Schermata di consenso dell'utente, aperta nel browser. |
| POST /api/oauth/token | Scambia un codice con un token, oppure aggiorna un token esistente. |
| POST /api/oauth/register | Registrazione dinamica del client (RFC 7591), facoltativa. |
| GET /.well-known/oauth-authorization-server | Metadati di discovery. |
| GET /.well-known/oauth-protected-resource | Metadati della risorsa, usati dai client MCP. |
Durata dei token
Codice di autorizzazione 10 min Monouso, legato a PKCE.
Token di accesso 7 giorni Bearer per le chiamate a /api/v1.
Refresh token 30 giorni Ruotato a ogni utilizzo.
Refresh
Ogni aggiornamento restituisce un nuovo refresh token e revoca il precedente: sovrascrivi sempre quello salvato. Se un aggiornamento restituisce invalid_grant, riporta l'utente al passaggio 1.
Sicurezza
- Conserva i token lato server, associati al tuo utente. Non inviarli mai al browser né a un repository pubblico.
- I token vengono revocati nel momento in cui l'utente scollega la tua app.
- Usa URI di reindirizzamento https in produzione. http è accettato per i test in locale.
- I token OAuth non concedono mai permessi di amministratore, qualunque scope sia approvato.