Se stai sviluppando la piattaforma per sviluppatori Zendesk, è probabile che a un certo punto ti siano imbattuti in errori 401 o 403. Questi due codici di stato rappresentano un’ampia percentuale di richieste API non riuscite che vediamo da parte degli sviluppatori, soprattutto all’inizio del ciclo di vita di un’integrazione.

Sebbene entrambi gli errori siano correlati al controllo degli accessi, non riescono per motivi molto diversi e richiedono approcci di debug diversi. Trattarli come intercambiabili spesso porta a perdite di tempo e ripetute richieste non riuscite.

In questo post, illustreremo come funzionano gli errori 401 e 403 in Zendesk, come diagnosticarli rapidamente e come risolverli in tutta sicurezza usando esempi pratici e procedure di risoluzione dei problemi.

Cosa imparerai

Alla fine di questo post, capirai:

  • La differenza tra 401 Non autorizzato e 403 Vietato in Zendesk
  • Come autenticarsi correttamente usando token API, token di accesso OAuth e JWT
  • In che modo gli ambiti OAuth influiscono sull’autorizzazione
  • Come diagnosticare intestazioni non corrette, sottodomini errati e credenziali scadute

 

Comprensione di 401 vs 403

Sebbene entrambi i codici di stato siano correlati al controllo dell’accesso, non riescono nelle diverse fasi dell’elaborazione della richiesta.

401 Non autorizzato

Una risposta 401 significa che l’API Zendesk non ha potuto autenticare la richiesta. Zendesk non è stato in grado di determinare chi sia il chiamante, quindi non tenta di valutare le autorizzazioni o la logica aziendale.

Le cause più comuni includono:

  • Intestazioni di autorizzazione mancanti o non corrette
  • Codifica Base64 errata per l’autenticazione di base
  • Formattazione errata di email e token
  • Token API scaduti o revocati
  • Uso di token OAuth in un’intestazione di autenticazione di base
  • JWT non validi o scaduti per la messaggistica

Se ricevi un errore 401, concentrati prima su come viene autenticata la richiesta, non su cosa sta tentando di fare.

403 Operazione proibita

Una risposta 403 indica che la richiesta è stata autenticata correttamente, ma l’identità autenticata non dispone dell’autorizzazione per eseguire l’azione richiesta.

Le cause tipiche includono:

  • Token OAuth senza ambiti obbligatori
  • Uso delle credenziali degli utenti finali per chiamare gli endpoint riservati agli agenti
  • Tentativo di accedere a risorse appartenenti a un altro brand
  • Limitazioni IP abilitate per l’account
  • Account agente sospesi o declassati

Se ricevi un errore 403, l’autenticazione funziona correttamente. Il problema è l’autorizzazione.

 

Un rapido flusso diagnostico

Quando si esegue il debug dei problemi di accesso, il modo più rapido è isolare il problema passo dopo passo.

Inizia provando la tua richiesta con curl. Se la richiesta curl non riesce, è probabile che il problema riguardi le credenziali o la configurazione dell’account, non il codice dell’applicazione.

Quindi, conferma di chiamare il sottodominio Zendesk corretto. Le credenziali hanno l’ambito di un ambiente specifico e i token sandbox e di produzione non sono intercambiabili.

Quindi, verifica di usare il metodo di autenticazione corretto. La combinazione di autenticazione di base, OAuth e JWT è una fonte comune di errore.

Controlla il ruolo dell’utente autenticato. Molti endpoint richiedono autorizzazioni di agente o amministratore, anche se l’autenticazione riesce.

Se usi OAuth, verifica che il token includa gli ambiti richiesti dall’endpoint.

Infine, considera dove è in esecuzione la richiesta. Le richieste provenienti dal browser sono spesso bloccate dalle policy CORS (Cross Browser Resource Sharing) quando si usa l’autenticazione di base del token API o altri flussi lato client non supportati. Se devi chiamare l’API da un browser, usa un flusso OAuth che supporti CORS oppure indirizza le richieste tramite un servizio di backend o un’app Zendesk usando il client ZAF . Per ulteriori informazioni sulle richieste CORS, consulta Esecuzione di richieste CORS lato client all’API di ticketing. 

 

Autenticazione corretta

L’autenticazione avviene prima di qualsiasi controllo delle autorizzazioni o della logica aziendale. Se l’autenticazione non riesce, Zendesk non può associare la richiesta a un utente o a un’integrazione e restituisce un errore 401.

Zendesk supporta diversi metodi di autenticazione, ciascuno con severi requisiti di formattazione.

Autenticazione con token API

I token API usano l’autenticazione di base, in cui il nome utente include il suffisso /token.

Il formato corretto è:

curl -v \
  -u "agent@example.com/token:YOUR_API_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/tickets.json"

Un errore comune che si traduce in un errore 401 è l’omissione del suffisso /token :

emailAddress:APITOKEN

In Node.js, un esempio funzionante è il seguente:

import fetch from "node-fetch";
import btoa from "btoa";

const subdomain = "your_subdomain";
const email = "agent@example.com";
const token = process.env.API_TOKEN;

const response = await fetch(
  `https://${subdomain}.zendesk.com/api/v2/users/me.json`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.status, await response.text());

 

Autenticazione OAuth

I token di accesso OAuth sono comunemente usati per le integrazioni che richiedono credenziali di lunga durata o un controllo dettagliato delle autorizzazioni. I token OAuth devono essere inviati usando lo schema di autenticazione Bearer . Il formato corretto dell’intestazione è:

Authorization: Bearer ACCESS_TOKEN

Esempio di richiesta che usa curl:

curl \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"

In Node.js, un esempio funzionante è il seguente:

import fetch from "node-fetch";

const subdomain = process.env.SUBDOMAIN;
const token = process.env.OAUTH_TOKEN;

const url = `https://${subdomain}.zendesk.com/api/v2/users/me.json`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

console.log(response.status, await response.text());

Una causa comune degli errori 401 non autorizzati quando si usa OAuth è l’invio di un token di accesso valido con lo schema di autenticazione errato. In questo caso, Zendesk non è in grado di autenticare la richiesta e restituisce un 401 prima di valutare gli ambiti o le autorizzazioni.

I token OAuth introducono anche il concetto di ambiti, che definiscono in modo esplicito le azioni che il token può eseguire. Un token può autenticarsi correttamente, ma restituire comunque una risposta 403 Forbidden se non ha gli ambiti richiesti dall’endpoint chiamato.

Ad esempio, un token con ticket:read può recuperare i dati dei ticket ma non può creare o aggiornare i ticket. Il tentativo di un’operazione di scrittura senza l’ambito appropriato comporterà costantemente un errore 403. 

403: You do not have access to this resource

In questo caso, l’autenticazione funziona come previsto, ma il token deve essere rigenerato con gli ambiti corretti. Per ulteriori informazioni sugli ambiti, consulta Token OAuth per tipi di concessione.

 

Autenticazione JWT per la messaggistica

Quando si implementa la messaggistica Zendesk nelle applicazioni web o mobili, l’autenticazione JWT viene usata per identificare in modo sicuro gli utenti finali. In questo modello, il backend è responsabile della generazione e della firma di un JSON Web Token (JWT) usando il segreto configurato nel Centro amministrativo. Zendesk convalida il token prima di consentire l’associazione della sessione di messaggistica a un utente.

A differenza dei token API o OAuth, i JWT di messaggistica richiedono attestazioni e informazioni di intestazione specifiche che consentano a Zendesk di risolvere correttamente l’identità dell’utente.

Un JWT di messaggistica deve includere almeno:

  • kid : l’ID chiave del Centro amministrativo Zendesk. Deve essere incluso nell’intestazione JWT, non nel payload.
  • external_id : identificatore univoco per l’utente. Zendesk usa questo valore come chiave primaria durante la corrispondenza o la creazione di record utente.
  • ambito : deve essere impostato su "utente", a indicare che il token è destinato all'autenticazione degli utenti finali nella messaggistica.

Ulteriori attestazioni come name, emailed email_verified sono facoltative e possono essere incluse per compilare i dettagli utente nell’interfaccia agente o assistenza la corrispondenza delle identità basata su email.


Esempio di generatore JWT Node.js: 

import jwt from "jsonwebtoken";
const payload = {
  scope: "user",
  external_id: "user_12345",
  name: "Jane Doe",
  exp: Math.floor(Date.now() / 1000) + (5 * 60)
};

const token = jwt.sign(payload, process.env.ZENDESK_JWT_SECRET, {
	keyid: process.env.ZENDESK_KEYID,
});

console.log(token);

Se mancano attestazioni obbligatorie come external_id o scope, o se il token è firmato con il segreto errato, Zendesk restituirà una risposta 401 Non autorizzato.


Le cause più comuni degli errori 401 correlati a JWT includono:

  • Uso di un segreto JWT dall’ambiente sbagliato (sandbox e produzione)
  • Invio di un token scaduto o con attestazioni basate sul tempo non valide
  • Omissione di attestazioni obbligatorie come external_id o scope 
  • Firma del token con un segreto errato o ruotato
  • Invio di un JWT non valido o codificato in modo errato

Quando si esegue il debug dei problemi di autenticazione della messaggistica, conferma prima che il token sia firmato con il segreto corretto e includa le attestazioni richieste. Se l’autenticazione ha esito positivo ma il comportamento dell’identità dell’utente è imprevisto, controlla i valori usati per external_id e gli eventuali campi di identità facoltativi per assicurarti che siano stabili e coerenti tra le sessioni. Per maggiori informazioni, consulta Autenticazione degli utenti nell’applicazione.
 

Cause comuni degli errori 401

Una risposta 401 significa che Zendesk non ha potuto autenticare la richiesta e non è stato in grado di determinare l’identità del chiamante.

Molto spesso, ciò è causato da intestazioni di autorizzazione costruite in modo errato, token disabilitati o mancate corrispondenze nell’ambiente.

Le intestazioni di autenticazione di base devono essere formattate come segue o equivalente:

headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
}

Caratteri imprevisti, spazi vuoti o problemi di codifica causano spesso errori silenziosi.

Infine, ricorda che l’API REST di Zendesk non assistenza l’autenticazione dell’origine del browser. Le richieste JavaScript lato client non riusciranno a causa di CORS, cookie di sessione mancanti e flussi di autenticazione non supportati. Usa invece un servizio di backend o un’app Zendesk creata con il client ZAF .

 

Cause comuni degli errori 403

Una risposta 403 indica che Zendesk ha autenticato la richiesta, ma ha negato l’accesso a causa delle regole di autorizzazione.

La causa più comune è la mancanza di ambiti OAuth . Ad esempio, un token con ticket:read può recuperare i ticket ma non può crearli o aggiornarli. I tentativi di scrittura restituiscono costantemente un errore 403.

Gli ambiti OAuth non possono essere modificati dopo la creazione del token. Se gli ambiti non sono corretti, è necessario generare un nuovo token.

Un’altra fonte comune di confusione è il tentativo di chiamare gli endpoint riservati agli agenti usando le credenziali degli utenti finali. I token OAuth per gli utenti finali possono funzionare per /users/me, ma restituiscono 403 quando si chiamano endpoint con limitazioni come ticket, viste o campi ticket.

Altre cause frequenti includono la revoca dei token, le limitazioni agli elenchi IP consentiti e le limitazioni di accesso multibrand. In questi casi, la richiesta viene rifiutata perché le credenziali non sono più attive o perché l'utente non soddisfa criteri di accesso specifici.

 

Un approccio dettagliato alla risoluzione dei problemi

1. Convalida le credenziali in isolamento In caso di dubbio, inizia rimuovendo il codice dell’applicazione dall’equazione. Convalida le tue credenziali usando curl :

curl -v \
  -u "email/token:token" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"
  • In caso di errore: È probabile che il problema sia dovuto alle credenziali o a un problema correlato all’account.
  • In caso di esito positivo: Le credenziali sono valide. Il problema risiede nella logica o nell’ambiente dell’applicazione. Vai al passaggio 2.

2. Verifica le limitazioni CORS: Se il comando curl funziona ma l’applicazione lato client non riesce, è probabile che tu stia rispettando le limitazioni CORS.

Apri la console per sviluppatori del browser e controlla l’errore. Se visualizzi un errore 401/403 accompagnato da un messaggio della console relativo a Access-Control-Allow-Origin, significa che il browser sta bloccando la richiesta prima che Zendesk possa elaborarla.

3 Esamina le intestazioni delle richieste non elaborate Se stai eseguendo codice lato server (Node.js, Python, PHP, ecc.) e stai ancora riscontrando problemi:.

  • Registra l’intestazione Autorizzazione: Stampa la stringa esatta inviata dall’applicazione. Assicurati che non ci siano spazi nascosti o prefissi errati (ad esempio, assicurati che Basic e Bearer siano usati correttamente).
  • Verifica ambiente: Conferma che l’applicazione ha come target il sottodominio corretto. È comune scegliere come destinazione accidentale un URL sandbox con credenziali di produzione o viceversa.

4 Verifica ambiti e attestazioni Se l’autenticazione ha esito positivo ma ricevi il messaggio 403 Vietato, il token potrebbe non disporre delle autorizzazioni necessarie.

  • Per OAuth: Verifica gli ambiti attuali chiamando l’endpoint /api/v2/oauth/tokens/current . Assicurati che il token abbia l’ambito richiesto per la risorsa a cui stai tentando di accedere.

  • Per la messaggistica/JWT: Riconvalida il payload JWT. Assicurati che il kid (ID chiave) corrisponda alla configurazione Zendesk e che il segreto di firma usato per generare il token sia corretto.

     

Considerazioni finali

La maggior parte degli errori 401 e 403 sulla piattaforma per sviluppatori Zendesk deriva da un numero limitato di configurazioni errate prevedibili. Una volta separati chiaramente gli errori di autenticazione dagli errori di autorizzazione, il debug diventa molto più veloce e affidabile.

Convalidando le credenziali in anticipo, confermando ambiti e ruoli e seguendo un approccio diagnostico strutturato, puoi risolvere rapidamente questi problemi ed evitare che si ripresentino in produzione.

Per maggiori dettagli, consulta la documentazione Zendesk sull’accesso ai token API, l’autenticazione OAuth, ilframework dell’app Z endeske l’autenticazione JWT di messaggistica.

Avvertenza sulla traduzione: questo articolo è stato tradotto usando un software di traduzione automatizzata per fornire una comprensione di base del contenuto. È stato fatto tutto il possibile per fornire una traduzione accurata, tuttavia Zendesk non garantisce l'accuratezza della traduzione.

Per qualsiasi dubbio sull'accuratezza delle informazioni contenute nell'articolo tradotto, fai riferimento alla versione inglese dell'articolo come versione ufficiale.

Powered by Zendesk