> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Autenticazione MCP di Didit: accedi con Didit (OAuth) > Come Didit MCP si autentica: OAuth 2.1 con PKCE, registrazione dinamica del client, metadati della risorsa, scope, ruoli e connessione per client. Il server MCP di Didit si autentica con **Accedi con Didit** (OAuth 2.1). Agisce come **utente** Didit con le autorizzazioni del ruolo che hai nella console — **non esiste una modalità con chiave API**. *** ## Accedi con Didit Il server ospitato (`https://mcp.didit.me/mcp`) è un **server delle risorse** OAuth 2.1. La **Didit Business Console** (`business.didit.me`) è il **server di autorizzazione** che ospita la schermata di consenso ed emette i token. Il tuo client MCP esegue automaticamente il flusso standard: **1. Scoperta** Il client invia una richiesta a `/mcp` senza token e riceve `401` con un'intestazione `WWW-Authenticate: Bearer` il cui `resource_metadata` punta ai metadati della risorsa protetta (RFC 9728): ```text theme={null} https://mcp.didit.me/.well-known/oauth-protected-resource/mcp ``` Quel documento indica la risorsa (`https://mcp.didit.me/mcp`), il server di autorizzazione (`https://business.didit.me`) e gli scope supportati. Lo stesso documento è disponibile anche alla radice dell'origine, `https://mcp.didit.me/.well-known/oauth-protected-resource`, per i client che provano prima quel percorso. **2. Registrazione (registrazione dinamica del client)** Il client legge i metadati del server di autorizzazione all'indirizzo `https://business.didit.me/.well-known/oauth-authorization-server` e, se non ha ancora un client id, si registra presso il `registration_endpoint` (RFC 7591). Non devi predisporre nulla: i client locali con callback loopback o nativo (Claude Code, Cursor, MCP Inspector) e i client cloud con un callback verificato (Claude) si registrano in questo modo. Un URL di callback remoto che Didit non ha verificato viene rifiutato con `invalid_redirect_uri`; per quel client è necessario che un operatore lo registri prima. **3. Autorizzazione (PKCE)** Il client apre `https://business.didit.me/authorize` con una challenge PKCE S256. Accedi (o ti registri) e vedi esattamente quali autorizzazioni vengono richieste. I client sono pubblici: l'endpoint del token non accetta alcun segreto client (`token_endpoint_auth_methods_supported` è `none`), quindi è PKCE a legare il codice al client. **4. Consenso** Approvi. La console crea una sessione per quell'app, vincolata agli scope che hai approvato, e restituisce un codice di autorizzazione, che il client scambia al `token_endpoint` per un token di accesso e un token di aggiornamento. **5. Chiamata degli strumenti** Il client invia l'access token con ogni richiesta. L'MCP valida il token tramite introspezione del token RFC 7662 presso il servizio di autenticazione di Didit (i token sono opachi, non JWT), legge le autorizzazioni della tua organizzazione dalla risposta dell'introspezione del token e agisce come **te** per la durata di quella richiesta. ### Scope I metadati della risorsa espongono tre scope. La schermata di consenso mostra in linguaggio semplice quelli richiesti da un client: | Scope | Concede | | - | - | | `didit:management` | Gestisci la tua area di lavoro: `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` e `analytics`. | | `didit:verification` | Esegui e rivedi le verifiche: `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` e `analytics`. | | `didit:staff` | Riservato agli account dello staff di Didit. Non sblocca nulla per un account normale, e la build open source non definisce strumenti riservati allo staff. | Entrambi gli scope includono `analytics`. Gestire `lists` richiede `didit:management`; accedere a `blocklist` richiede `didit:verification`. Il [riferimento degli strumenti](https://docs.didit.me/it/integration/mcp/tools.md) elenca lo scope di ciascuno strumento. Gli scope che approvi vengono riportati nel token e applicati lato server, quindi un'app collegata con il solo `didit:verification` viene rifiutata sulla superficie di gestione anche quando il tuo ruolo lo consentirebbe. Il server di autorizzazione conosce anche gli scope OpenID (`openid profile email`): una connessione che richiede solo questi può identificare chi sei e nient'altro. Le autorizzazioni effettive di un'app sono l'**intersezione** tra gli scope approvati e il tuo ruolo nella console, mai la più ampia delle due. Per creare una sessione di verifica con `didit_session_create` servono lo scope `didit:verification` **e** un ruolo con `create:sessions` o `write:sessions`. Il ruolo **Developer** include `create:sessions`. Approvare il solo `didit:management` non consente la creazione di sessioni, anche se il tuo ruolo ha l'autorizzazione richiesta. ### Ruoli e autorizzazioni Il token rilasciato dal server ospitato rappresenta **te**, quindi l'agente può lavorare su **ogni organizzazione di cui fai parte** con una singola connessione: gli strumenti inter-app (`didit_session_search`, `didit_analytics`, `didit_context_get` e gli altri strumenti `*_search`) aggregano automaticamente i dati di tutte. Il tuo **ruolo è sempre applicato** dal backend di Didit, per ogni organizzazione. Ogni strumento corrisponde a una sola stringa di autorizzazione del backend (ad esempio `write:sessions` per `didit_session_update_status`, `delete:sessions` per `didit_session_delete`); il [riferimento degli strumenti](https://docs.didit.me/it/integration/mcp/tools.md) la mostra per ogni strumento. Il server verifica inoltre questa autorizzazione prima di inviare la richiesta, usando le autorizzazioni che la risposta dell'introspezione del token riporta per la tua organizzazione: * In modalità `enforce` uno strumento che il tuo ruolo non può eseguire viene escluso da `tools/list`, e chiamarlo comunque restituisce un errore `missing_scope` che indica l'autorizzazione (`"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`). * In modalità `shadow` (predefinita del server) ogni strumento viene elencato e la chiamata arriva al backend, che risponde con `403` se il ruolo non ha l'autorizzazione; l'esito viene solo registrato nel registro di audit del server. In ogni caso, l'MCP non concede mai più di quanto il tuo ruolo nella console già consenta. Un `READER` può elencare e leggere; un `OWNER` o un `ADMIN` può scrivere ed eliminare. ### Durata dei token Un'app approvata ottiene una propria sessione, separata dalla sessione del browser da cui l'hai approvata. Gli access token hanno vita breve; il client li rinnova in modo trasparente con il refresh token (`grant_types_supported` include `refresh_token`), e il rinnovo mantiene gli scope dell'app e resta vincolato a quell'app. Se un rinnovo fallisce (ad esempio dopo che hai disconnesso l'app), il client esegue di nuovo **Accedi con Didit** alla chiamata successiva. Il logout dalla console non disconnette le app collegate, e disconnettere un'app non ti disconnette mai da nessuna parte. ### Disconnettere un'app **1. Dalla console** **Impostazioni → Autenticazione → App collegate** elenca ogni app che hai approvato, con il nome registrato e le autorizzazioni concesse. **Disconnetti** interrompe immediatamente l'accesso di quell'app: sia il suo access token sia il suo refresh token smettono di funzionare, e nient'altro viene modificato. **2. Dall'app (RFC 7009)** Un client può revocare il proprio accesso inviando il token al `revocation_endpoint` del server di autorizzazione, indicato nei metadati su `https://business.didit.me/.well-known/oauth-authorization-server`. Come richiesto dall'RFC 7009, una chiamata riuscita restituisce `200` indipendentemente dal fatto che il token fosse ancora valido, quindi la risposta non ti dice mai se un token era valido. Un `503` significa che la revoca non è stata applicata: considera il token ancora valido e riprova. ```bash theme={null} curl -X POST https://business.didit.me/api/auth/oauth-revoke \ -H "Content-Type: application/json" \ -d '{"token": "", "token_type_hint": "refresh_token", "client_id": ""}' ``` > [!NOTE] > > **Perché nessuna chiave API?** Ogni tool MCP chiama gli endpoint della console con ambito utente (`/organization/{org}/application/{app}/…`), che autorizzano un token Bearer con privilegi per ruolo e **rifiutano `x-api-key`**. Una chiave API dell'applicazione serve per chiamare direttamente la [REST API](https://docs.didit.me/openapi-25.json) dal tuo backend (ad esempio per creare sessioni), non per questo MCP. `didit_org_list_api_keys` mostra i metadati delle chiavi con i valori oscurati; il tool che rivela una chiave in chiaro è nascosto sul connettore ospitato. *** ## Connettere ogni client Ogni client segue lo stesso flusso; cambia solo il modo in cui gli fornisci l'URL. > [tab] Claude > > Usa il deep link che la Business Console mostra nella pagina di integrazione. Apre claude.ai con la finestra **Add custom connector** già compilata: > > ```text theme={null} > https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp > ``` > > Conferma, quindi completa **Accedi con Didit**. Claude Desktop usa lo stesso URL in **Settings → Connectors → Add custom connector**. Dettagli in [Connect Claude](https://docs.didit.me/it/integration/mcp/claude.md). > [tab] Claude Code > > ```bash theme={null} > claude mcp add --transport http didit https://mcp.didit.me/mcp > ``` > > Poi esegui `/mcp` dentro Claude Code per avviare l'accesso tramite browser. > [tab] Cursor > > `~/.cursor/mcp.json`: > > ```json theme={null} > { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } } > ``` > > Cursor si registra da solo e apre il browser al primo utilizzo. > [tab] Client generico > > Indirizza qualsiasi client Streamable HTTP con supporto OAuth 2.1 verso `https://mcp.didit.me/mcp`. Deve: > > 1. Eseguire `POST /mcp`, ricevere `401` e leggere `resource_metadata` da `WWW-Authenticate`. > 2. Recuperare `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp`, poi i metadati del server di autorizzazione su `https://business.didit.me/.well-known/oauth-authorization-server`. > 3. Registrarsi al `registration_endpoint` se non ha un client id. > 4. Eseguire il flusso del codice di autorizzazione con PKCE (S256) all'`authorization_endpoint`, quindi scambiare il codice al `token_endpoint`. > 5. Inviare `Authorization: Bearer ` in ogni `POST /mcp`. > > I client senza supporto OAuth possono passare da `npx -y mcp-remote@latest https://mcp.didit.me/mcp`, che esegue per loro i passaggi da 1 a 5. *** ## Errori di autenticazione ```text theme={null} HTTP 401 WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp" ``` Un `401` da `/mcp` significa che il token manca, è scaduto o è stato revocato: il client dovrebbe aggiornarlo o rieseguire **Accedi con Didit**. Un `403` o un errore `missing_scope` su un tool *specifico* significa di solito che il tuo **ruolo** non ha quell'autorizzazione (ad esempio un `READER` che tenta una scrittura) oppure che la connessione è stata approvata **senza lo scope** richiesto da quel tool, non che l'intera connessione sia guasta. Riconnettersi e approvare entrambi gli scope risolve il secondo caso; il primo richiede un cambio di ruolo. Se ogni tool fallisce, controlla **Impostazioni → Autenticazione → App collegate** nella console: un'app disconnessa lì deve essere approvata di nuovo. *** > [card] [Riferimento dei tool](https://docs.didit.me/it/integration/mcp/tools.md) > > Cosa fa ogni tool, il suo scope e l'autorizzazione del ruolo. > [card] [Avanzate](https://docs.didit.me/it/integration/mcp/advanced.md) > > Ruoli, comportamento tra app e self-hosting. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.