Il codice 403 SCOPE_MISMATCH per la Ricerca Ticket indica che il token di accesso inviato non include lo scope Desk API richiesto per chiamare l'endpoint di Ricerca Ticket; Zoho rifiuta la richiesta per motivi di autorizzazione. Questo accade solitamente dopo una modifica dello scope, un aggiornamento del token che ha perso gli scope, o quando a un'app non sono mai stati concessi gli scope di ricerca/ticket Desk [3][4].
Cosa significa
Lo strato di autorizzazione di Zoho confronta gli scope OAuth associati al token bearer con l'endpoint API che stai chiamando. L'endpoint di Ricerca Ticket richiede specifici scope di ricerca/ticket Desk; se il token non dispone di tali scope, l'API restituisce 403 SCOPE_MISMATCH anziché un errore di dati o sintassi [3]. L'errore è un fallimento di autorizzazione legato alle dichiarazioni degli scope OAuth, non alla sintassi COQL o della query.
Cause comuni
- Il tuo client/token OAuth è stato creato o aggiornato senza che gli scope di ricerca/ticket Desk fossero richiesti o approvati [3].
- L'utente o l'amministratore ha revocato il permesso dell'app o rimosso gli scope richiesti dopo il consenso iniziale [3][4].
- Hai aggiornato/ottenuto un token di accesso utilizzando un flusso di concessione diverso (o un client diverso) che non richiede gli stessi scope [4].
- Utilizzo di un token memorizzato nella cache a lunga durata emesso prima che tu aggiungessi lo scope di ricerca/ticket al client; il vecchio token non ha mai avuto il nuovo scope [3].
Come risolvere
- Conferma gli scope richiesti: verifica quali scope Desk richiede l'endpoint di Ricerca Ticket nella documentazione dell'API Zoho Desk o nelle note della tua integrazione, quindi elenca gli scope che la tua app deve richiedere.
- Aggiorna la richiesta OAuth: aggiungi gli scope di ricerca/ticket Desk richiesti al tuo URL di autorizzazione o al parametro scope nella richiesta del token.
- Richiedi nuovamente il consenso come utente/amministratore: apri l'URL di autorizzazione in modo che l'utente (o l'amministratore dell'organizzazione se è richiesto il consenso dell'amministratore) conceda nuovamente il set di scope aggiornato. Per l'accesso a livello di organizzazione, accedi come amministratore tramite Zoho Accounts > Applicazioni autorizzate.
- Genera un nuovo token di accesso: dopo il consenso, scambia il codice di autorizzazione (o utilizza il flusso di aggiornamento che richiede gli scope) per ottenere un nuovo token di accesso e verifica i suoi scope. Non riutilizzare il vecchio token.
- Testa la chiamata: ritenta la richiesta di Ricerca Ticket con il nuovo token e conferma che il 403 scompaia. Registra la dichiarazione dello scope del token per il debug futuro.
Quando escalare
Se la richiesta di nuovi scope e l'ottenimento di un nuovo token non risolvono il 403, apri un ticket di supporto con Zoho Desk. Includi il tuo ID client, l'elenco esatto degli scope che hai richiesto, l'ora della richiesta fallita e l'endpoint API completo e gli header (oscura i segreti); il supporto Zoho può verificare il consenso a livello di organizzazione e le mappature degli scope [3][4].