Collega la tua app a Notiondesk con OAuth

L'autenticazione OAuth consente ad altri clienti di connettere la tua app al loro spazio di lavoro senza dover condividere una chiave API. Il cliente accede a Notiondesk, verifica le richieste della tua app e le approva. La tua app riceve un token di accesso per l'API REST di Notiondesk, che il cliente può revocare in qualsiasi momento. Questo articolo illustra la procedura di registrazione dell'app, l'esecuzione del flusso di codice di autorizzazione OAuth 2.0 con PKCE, l'aggiornamento dei token e la gestione degli errori.

Quando utilizzare OAuth al posto di una chiave API

Ogni percorso API Notiondesk accetta entrambe le credenziali e risponde allo stesso modo: stessi ambiti, risposte ed errori.

Cosa deve sapere la tua app

Leggete gli endpoint dal documento dei metadati del server di autorizzazione anziché inserirli direttamente nel codice.

Esegui il tuo client OAuth su un server. I client basati su browser non sono supportati: mantieni lo scambio di token, i token e ogni chiamata API sul tuo backend.

Passaggio 1: Registra la tua app

Registrati una sola volta con la registrazione dinamica del cliente :

La risposta 201 Created contiene il tuo client_id e, poiché hai richiesto client_secret_post, un client_secret. Il segreto viene mostrato una sola volta: conservalo insieme agli altri segreti del server.

Con "token_endpoint_auth_method": "none", la tua app è un client pubblico senza segreti e PKCE protegge lo scambio del suo codice.

Invece di registrarti, puoi usare l'URL HTTPS di un documento di metadati del client come client_id. Notiondesk recupera il documento quando un cliente autorizza la tua app e lo memorizza nella cache per un massimo di cinque minuti.

Regole URI di reindirizzamento

curl -X POST "https://api.notiondesk.so/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Acme Reports", "redirect_uris": ["https://acme.example/oauth/callback"], "token_endpoint_auth_method": "client_secret_post"}'

• Utilizzare https o http su un host di loopback: 127.0.0.1, localhost o [::1].

• Un reindirizzamento di loopback corrisponde su qualsiasi porta. Qualsiasi altro reindirizzamento deve corrispondere esattamente.

• I caratteri jolly, i frammenti, le credenziali prima dell'host (user@), le barre rovesciate, i caratteri non ASCII e gli host codificati in percentuale vengono rifiutati.

• L'host che un cliente vede nella schermata di consenso proviene dai tuoi URI di reindirizzamento o dal tuo URL client_id. Registra solo gli host di tua proprietà.

Passaggio 2: Invia il cliente a Notiondesk

Crea un code_verifier casuale, quindi ricava il code_challenge come hash SHA-256 del verificatore, codificato in base64url ( PKCE ). Reindirizza il browser del cliente a:

https://api.notiondesk.so/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Fcallback
  &scope=read%20write
  &state=RANDOM_STATE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.notiondesk.so

• resource è obbligatorio e deve essere esattamente https://api.notiondesk.so: minuscolo, senza barra finale, senza percorso. Un valore mancante o diverso corrisponde a invalid_request.

• scope è un elenco separato da spazi. Richiedi solo gli ambiti utilizzati dalla tua app.

• state protegge dagli attacchi di tipo cross-site request forgery. Verificalo al ritorno del cliente.

Un token emesso per l'API REST Notiondesk funziona solo con l'API REST. Un token emesso per Workspace MCP viene rifiutato dall'API REST e viceversa.

Passaggio 3: Il cliente approva la tua app

Notiondesk mostra la schermata di consenso. Il cliente effettua l'accesso e visualizza il nome e l'host della tua app, il suo spazio di lavoro e gli ambiti della tua richiesta consentiti dal suo ruolo. Approva o rifiuta l'intera richiesta.

Le autorizzazioni che la tua app può ricevere dipendono dal ruolo dell'area di lavoro del cliente:

admin consente alla tua app di modificare il branding del centro assistenza, configurare le integrazioni i cui script vengono caricati sul centro assistenza pubblico ed eliminare i reindirizzamenti. Richiedilo solo se la tua app utilizza questi percorsi.

Il cliente non può approvare la richiesta quando:

• Il loro ruolo non consente nessuno degli ambiti che hai richiesto;

• Il loro spazio di lavoro non dispone di accesso alle API. La schermata di consenso mostra quindi "Il piano dello spazio di lavoro non include l'accesso alle API". L'accesso alle API richiede un piano Enterprise.

Dopo l'approvazione, il browser restituisce al tuo redirect_uri con un code, il tuo state e iss, l'identificativo del server di autorizzazione Notiondesk. Se il cliente nega, il reindirizzamento contiene invece error=access_denied.

Passaggio 4: Scambia il codice con i token

Il codice è valido per 60 secondi e funziona una sola volta:

Escludi client_secret per un client pubblico. La risposta:

scope elenca gli ambiti concessi dal cliente, che potrebbero essere inferiori a quelli richiesti. Memorizza entrambi i token sul tuo server.

Passaggio 5: Chiamare l'API Notiondesk

Invia il token di accesso come un bearer token, esattamente come una chiave API:

Gli ambiti del token sono limitati al ruolo corrente del cliente che lo approva: un cliente passato a Viewer lascia la tua app con solo read e un percorso che necessita di un ambito mancante risponde 403 insufficient_scope.

I budget di limitazione della velocità e i valori Idempotency-Key appartengono alla concessione. Ogni approvazione è una nuova concessione con i propri budget e chiavi, e un aggiornamento del token mantiene entrambi.

Passaggio 6: Aggiorna il token di accesso

Un token di accesso ha una durata di un'ora. Prima della sua scadenza, scambia il token di aggiornamento con una nuova coppia:

Ogni aggiornamento restituisce un nuovo token di aggiornamento valido per 30 giorni e invalida quello inviato. Conserva il nuovo token di aggiornamento prima di utilizzare il nuovo token di accesso.

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=THE_CODE \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d redirect_uri=https://acme.example/oauth/callback

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8f3c...",
  "scope": "read write"
}

curl "https://api.notiondesk.so/sites" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "nd-version: 2026-10-16"

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d refresh_token=THE_REFRESH_TOKEN

Non riutilizzare mai un refresh token. L'invio di un token già utilizzato revoca l'intera autorizzazione, token di accesso incluso, perché il riutilizzo implica che il token sia stato copiato. Il cliente dovrà quindi autorizzare nuovamente la tua app.

Come i clienti revocano la tua app

I proprietari e gli amministratori dello spazio di lavoro possono visualizzare tutte le app con accesso al proprio spazio di lavoro in Impostazioni > Sviluppatori > App connesse . Le app che utilizzano l'API REST mostrano la dicitura "API REST" nella colonna Accesso , insieme al nome dell'app, alla persona che l'ha autorizzata, ai relativi ambiti di autorizzazione e all'ultima attività. La revoca interrompe immediatamente l'autorizzazione: il token di accesso e il token di aggiornamento smettono di funzionare alla richiesta successiva.

Una sovvenzione, inoltre, termina spontaneamente:

• dopo 30 giorni senza aggiornamento;

• quando il suo token di aggiornamento viene riutilizzato.

Finché il cliente che approva non possiede il ruolo necessario per una determinata rotta, o il piano dell'area di lavoro non dispone dell'accesso API, le richieste vengono rifiutate. Funzionano di nuovo se il ruolo o il piano vengono ripristinati prima della scadenza della concessione.

Risoluzione dei problemi Notiondesk OAuth

Gli endpoint di autorizzazione e token rispondono agli errori OAuth standard, non all'errore API Notiondesk:

{"error": "invalid_grant", "error_description": "Invalid authorization code."}

L'endpoint di autorizzazione mostra direttamente questi errori e non reindirizza mai una richiesta non valida al tuo redirect_uri. Un consenso negato raggiunge la tua app solo tramite il reindirizzamento error=access_denied.

Le chiamate all'API stessa rispondono all'intestazione di errore API Notiondesk . Un token di accesso scaduto o revocato risponde con un codice 401 authentication_error e il messaggio "Chiave API non valida o mancante.", lo stesso messaggio che viene visualizzato per una chiave API inutilizzabile.

Domande frequenti

Cosa succederà dopo?

• Inizia a utilizzare l'API REST Notiondesk

• Autenticarsi con l'API Notiondesk utilizzando le chiavi API

• Disconnetti o revoca l'accesso a Workspace MCP