Se usi la piattaforma per sviluppatori Zendesk, è probabile che ti siano imbattuti in errori 401 o 403. Questi codici di stato tengono conto di molte richieste API non riuscite che vediamo da parte degli sviluppatori, soprattutto all’inizio del ciclo di vita di un’integrazione.

Sebbene entrambi gli errori riguardino il controllo degli accessi, non riescono per motivi diversi e richiedono approcci diversi. Se li consideri intercambiabili, potresti perdere tempo e generare ripetute richieste non riuscite.

Cosa imparerai

Alla fine di questo post, capirai:

  • La differenza tra gli errori 401 Non autorizzato e 403 Non consentito in Zendesk
  • Come diagnosticare rapidamente gli errori
  • Come autenticarsi correttamente con token API, token di accesso OAuth e JWT (JSON Web Token)
  • In che modo gli ambiti OAuth influiscono sull’autorizzazione
  • Come diagnosticare intestazioni non corrette, sottodomini errati e credenziali scadute
  • Come correggere gli errori in tutta sicurezza attraverso esempi pratici e passaggi per la risoluzione dei problemi

Differenza tra gli errori 401 e 403

Entrambi i codici di stato si riferiscono al controllo degli accessi, ma non riescono nelle diverse fasi del processo di richiesta.

401 - Non autorizzato

Una risposta 401 significa che l’API Zendesk non può autenticare la richiesta. Zendesk non è in grado di identificare il chiamante, quindi non valuta le autorizzazioni o la logica aziendale.

Le cause più comuni includono:

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

Se ricevi un errore 401, concentrati sul modo in cui la richiesta viene autenticata, non su ciò che tenta di fare la richiesta.

403 Operazione proibita

Una risposta 403 significa che Zendesk ha autenticato la richiesta, ma l’identità autenticata non ha l’autorizzazione necessaria per eseguire l’azione richiesta.

Le cause tipiche includono:

  • Token OAuth senza ambiti obbligatori
  • Credenziali degli utenti finali rispetto agli endpoint riservati agli agenti
  • Accesso a risorse che appartengono a un altro brand
  • Regole dell’elenco indirizzi IP consentiti
  • Account agente sospesi o declassati

Se ricevi l’errore 403, l’autenticazione ha esito positivo. Il problema è l’autorizzazione.

Un flusso diagnostico rapido

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

  1. Inizia con un test di arricciatura. Se la richiesta curl non riesce, è probabile che il problema riguardi le credenziali o la configurazione dell’account, non il codice dell’applicazione
  2. Conferma di chiamare il sottodominio Zendesk corretto. Le credenziali riguardano un ambiente specifico e i token sandbox e di produzione non vengono scambiati.
  3. Verifica di usare il metodo di autenticazione corretto. La confusione tra Basic Auth, OAuth e JWT spesso causa errori.
  4. Controlla il ruolo dell’utente autenticato. Molti endpoint richiedono autorizzazioni di agente o amministratore, anche se l’autenticazione riesce
  5. Se usi OAuth, verifica che il token includa gli ambiti richiesti dall’endpoint
  6. Infine, considera dove viene eseguita la richiesta. Le richieste provenienti dal browser spesso non riescono a causa delle policy CORS (Cross-Origin Resource Sharing) quando usi l’autenticazione di base con token API o altri flussi lato client non supportati. Se devi chiamare l’API da un browser, usa un flusso OAuth che supporta CORS, indirizza le richieste tramite un servizio di backend o usa un’app Zendesk con il client ZAF . Per ulteriori informazioni sulle richieste CORS, consulta Esecuzione di richieste CORS lato client all’API di ticketing .

Come autenticarsi correttamente

L’autenticazione viene eseguita 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 l’errore 401.

Zendesk supporta diversi metodi di autenticazione, ognuno con regole di formato rigorose.

Autenticazione con token API

I token API usano l’autenticazione di base e il nome utente deve includere il suffisso /token .

Il formato corretto è:

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

Un errore comune che restituisce un errore 401 è l’omissione del suffisso /token :

emailAddress:APITOKEN

Un esempio di Node.js:

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

Le integrazioni che richiedono credenziali di lunga durata o un controllo granulare delle autorizzazioni spesso usano OAuth. Invia token di accesso OAuth con lo schema Bearer . Usa questa intestazione:

Authorization: Bearer ACCESS_TOKEN

Esempio di richiesta con curl:

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

Un esempio di Node.js:

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 di 401 Non autorizzato con OAuth è un token di accesso valido inviato con lo schema errato. In tal caso, Zendesk non può autenticare la richiesta e restituisce 401 prima di valutare gli ambiti o le autorizzazioni.

I token OAuth usano anche ambiti che definiscono le azioni consentite. Un token può autenticarsi e restituire comunque 403 Forbidden se non dispone degli ambiti richiesti dall’endpoint.

Ad esempio, un token con ticket:read può recuperare i dati dei ticket ma non può creare o aggiornare i ticket. Un tentativo di scrittura senza l’ambito corretto restituisce sempre un errore 403.

403: You do not have access to this resource

In questo caso, l’autenticazione funziona, ma devi rigenerare il token con gli ambiti corretti. Per dettagli sull’ambito, consulta Token OAuth per tipi di concessione .

Come usare l’autenticazione JWT per la messaggistica

La messaggistica Zendesk nelle app web o mobili usa JWT per identificare gli utenti finali. Il backend deve firmare un JSON Web Token con il segreto dal Centro amministrativo. Zendesk convalida il token prima di associare la sessione di messaggistica a un utente.

I JWT di messaggistica necessitano di valori di intestazione e attestazione specifici per consentire a Zendesk di risolvere l’identità dell’utente.

Un JWT di messaggistica deve includere almeno:

  • kid : l’ID chiave del Centro amministrativo nell’intestazione JWT, non il payload
  • external_id : identificatore univoco per l’utente
  • ambito : il valore “user” per l’autenticazione dell’utente finale nella messaggistica

Le attestazioni facoltative come name , email ed email_verified possono compilare i dettagli utente nell’interfaccia agente e assistenza la corrispondenza delle identità basata sulle 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 le attestazioni obbligatorie come external_id o scope sono assenti o se firmi con il segreto sbagliato, Zendesk restituisce 401 Non autorizzato.

Cause 401 comuni con JWT:

  • Un segreto JWT dall’ambiente sbagliato (sandbox vs produzione)
  • Un token scaduto o attestazioni basate sul tempo non valide
  • Le attestazioni obbligatorie come external_id o scope non sono presenti
  • Un token firmato con un segreto errato o ruotato
  • JWT non valido o codificato in modo errato

Per eseguire il debug dell’autenticazione della messaggistica, conferma prima il segreto corretto e le attestazioni obbligatorie. Se l’autenticazione riesce ma il comportamento dell’identità sembra disattivato, verifica i valori stabili e coerenti per external_id ed eventuali campi di identità facoltativi nelle sessioni. Per ulteriori informazioni, consulta Autenticazione degli utenti nella tua applicazione .

Cause comuni degli errori 401

Una risposta 401 significa che Zendesk non può autenticare la richiesta e non può determinare l’identità del chiamante.

Le intestazioni di autorizzazione errate, i token disabilitati o le mancate corrispondenze dell’ambiente causano la maggior parte delle risposte 401.

Formatta le intestazioni di autenticazione di base in questo modo:

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

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

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

Cause comuni degli errori 403

Una risposta 403 indica che Zendesk ha autenticato la richiesta, ma le regole di autorizzazione negano l’accesso.

La mancanza di ambiti OAuth causa la maggior parte delle 403 risposte. Ad esempio, un token con ticket:read può recuperare i ticket ma non può crearli o aggiornarli. Un tentativo di scrittura restituisce sempre un errore 403.

Non puoi modificare gli ambiti OAuth dopo la creazione del token. Se gli ambiti sono errati, genera un nuovo token.

Un altro problema frequente: una chiamata a endpoint riservati agli agenti con credenziali di utente finale. I token OAuth degli utenti finali possono chiamare /users/me , ma restituiscono 403 per gli endpoint con limitazioni come ticket, viste o campi ticket.

Altre cause includono la revoca dei token, le regole di inserimento negli elenchi IP consentiti e i limiti di accesso multibrand. In questi casi, Zendesk rifiuta la richiesta perché le credenziali non sono attive o perché l’utente non soddisfa i criteri di accesso.

Un approccio dettagliato alla risoluzione dei problemi

1. Convalida le credenziali in isolamento:

curl -v \
  -u "email/token:token" \
  "https://yoursubdomain.zendesk.com/api/v2/users/me.json"
  • In caso di errore: Il problema probabilmente riguarda le credenziali o l’account.
  • In caso di esito positivo: Le credenziali sono valide. Il problema risiede nella logica dell’applicazione o nell’ambiente. Vai al passaggio 2.

2. Verifica i limiti CORS:

Se curl funziona ma l’app lato client non funziona, è probabile che tu abbia raggiunto le limitazioni CORS. Apri la console per sviluppatori del browser e verifica l’errore. Se vedi un 401/403 con il messaggio Controllo accessi-Consenti-Origine, il browser blocca la richiesta prima che Zendesk possa elaborarla.

3. Ispeziona le intestazioni delle richieste non elaborate:

  • Registra l’intestazione Autorizzazione: Stampa la stringa esatta inviata dall’app. Conferma l’assenza di spazi vuoti nascosti e correggi i prefissi come Base o Portante.
  • Verifica ambiente: Conferma che l’app sia indirizzata al sottodominio corretto. Molti team scelgono come target un URL sandbox con credenziali di produzione o viceversa.

4. Verifica ambiti e attestazioni:

  • Per OAuth: Chiama /api/v2/oauth/tokens/current per elencare gli ambiti correnti. Conferma che il token ha l’ambito richiesto dalla risorsa.
  • Per la messaggistica/JWT: Riconvalida il payload JWT. Conferma che l’ID chiave (ID chiave) corrisponda alla configurazione Zendesk e che tu abbia usato il segreto di firma corretto.

Considerazioni finali

La maggior parte degli errori 401 e 403 sulla piattaforma per sviluppatori Zendesk deriva da una serie limitata di configurazioni errate prevedibili. Separa l’autenticazione dall’autorizzazione per accelerare la diagnosi e aumentare l’affidabilità.

Convalida in anticipo le credenziali, conferma ambiti e ruoli e segui un approccio diagnostico strutturato per risolvere rapidamente i problemi ed evitare che si ripetano in produzione.

Per maggiori dettagli, consulta la documentazione Zendesk sull’accesso con token API , l’autenticazione OAuth , il framework dell’app Zendesk e 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