Autenticarsi con l'API Notiondesk utilizzando le chiavi API

Ogni richiesta API di Notiondesk viene autenticata con un token bearer: una chiave API dell'area di lavoro o un token di accesso OAuth per le app che agiscono per conto di altri clienti di Notiondesk. Questo articolo mostra come creare una chiave API di Notiondesk, sceglierne gli ambiti, inviarla con le richieste e ruotarla o revocarla.

Utilizza una chiave API per l'automazione che esegui per il tuo spazio di lavoro: uno script, un'attività pianificata, un passaggio di CI o uno strumento interno. Se stai creando un'app a cui si connettono altri clienti di Notiondesk, utilizza OAuth .

Prima di iniziare

• Il tuo spazio di lavoro è basato su un piano Enterprise.

• Sei il proprietario dello spazio di lavoro o un amministratore.

Crea una chiave API Notiondesk

1. Nella tua dashboard Notiondesk, fai clic su Impostazioni .

2. Nella sezione Area di lavoro , apri Sviluppatori , quindi Chiavi API .

3. Fai clic su Crea chiave .

4. Inserisci un'etichetta che indichi a cosa serve la chiave, ad esempio CI automation o Redirect import.

5. Nella sezione Ambiti , seleziona solo gli ambiti necessari all'integrazione. Vedi Scegliere gli ambiti corretti .

6. Scegli una data di scadenza : 30 giorni , 90 giorni , 1 anno o nessuna scadenza .

7. Fai clic su Crea .

8. Fai clic su Copia chiave e salva la chiave nel tuo gestore di segreti o nelle variabili d'ambiente.

9. Fai clic su " Ho memorizzato la chiave" .

La chiave viene mostrata una sola volta. Se la perdi, ruota la chiave per ottenere un nuovo segreto.

Nota: se il pulsante Crea mostra un lucchetto e il tooltip "Disponibile nei piani con accesso API.", il tuo piano non include l'API. Facendo clic su di esso si aprono le opzioni di aggiornamento.

Scegli gli strumenti di puntamento giusti

Uno scope è un permesso associato a una chiave. Ogni percorso API Notiondesk richiede uno scope e una chiave può contenerne diversi.

Assegna a ciascuna integrazione il set minimo di ambiti necessari:

Come i ruoli dello spazio di lavoro limitano un elemento chiave

Una chiave non fa mai più di quello che la persona che l'ha creata può fare nel tuo spazio di lavoro.

Se il ruolo del creatore cambia, anche gli ambiti effettivi della chiave cambiano di conseguenza. Se il creatore abbandona l'area di lavoro, la chiave smette di funzionare. Per gestire i ruoli, consultare la sezione "Come invitare un membro del team" .

Invia la chiave con ogni richiesta

Invia la chiave nell'intestazione Authorization con lo schema Bearer:

Un 200 OK con un elenco dei tuoi centri di assistenza conferma che il tasto funziona. Un tasto funziona per ogni centro di assistenza nel relativo spazio di lavoro.

La stessa richiesta in JavaScript:

E in Python:

Conserva in un luogo sicuro la tua chiave API Notiondesk

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

const response = await fetch("<https://api.notiondesk.so/sites>", {
  headers: {
    Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
    "nd-version": "2026-10-16",
  },
});

const sites = await response.json();

import os
import requests

response = requests.get(
    "<https://api.notiondesk.so/sites>",
    headers={
        "Authorization": f"Bearer {os.environ['NOTIONDESK_API_KEY']}",
        "nd-version": "2026-10-16",
    },
)
sites = response.json()

• Conserva le chiavi sul tuo server. Non inserire mai una chiave nel codice del browser, in un'app per dispositivi mobili o in un repository pubblico.

• Archivia le chiavi nelle variabili d'ambiente o in un gestore di segreti, non nel codice sorgente.

• Crea una chiave per ogni integrazione, con la sua etichetta specifica, in modo da poter revocarne una senza compromettere le altre.

• Scegli una data di scadenza per le chiavi utilizzate dagli script temporanei.

• Ruota una chiave quando qualcuno che la conosceva lascia il tuo team.

• Controlla la colonna "Ultimo utilizzo" e revoca le chiavi che nessuno utilizza.

Ruota o revoca un tasto

Apri Impostazioni > Sviluppatori > Chiavi API e utilizza il menu in fondo alla riga della chiave.

La funzione Ruota sostituisce il segreto. Conferma con Ruota : il segreto corrente smetterà di funzionare immediatamente e il nuovo segreto verrà visualizzato una sola volta. Aggiorna subito la tua integrazione. Una chiave scaduta non può essere ruotata; creane una nuova.

Revoca disabilita definitivamente il tasto. Conferma con Revoca : le automazioni che utilizzano il tasto smettono di funzionare immediatamente e l'operazione non può essere annullata.

Risoluzione dei problemi di autenticazione

WWW-Authenticate: Bearer error="insufficient_scope", scope="sync"

Domande frequenti

Cosa succederà dopo?

• Inizia a utilizzare l'API REST Notiondesk

• Collega la tua app a Notiondesk con OAuth

• Gestire gli errori dell'API Notiondesk, i limiti di frequenza e i tentativi di ripetizione.