Una chiave API permette a un programma di operare sui dati del tuo account tramite l'API di LocalUp o il server MCP. Questa guida spiega come crearne una con il solo accesso necessario e come tenerla al sicuro.
Prima di iniziare:
- L'accesso all'API deve essere attivo per il tuo account (la voce API è presente nella barra laterale) e il tuo ruolo deve consentire la gestione delle chiavi API.
- Decidi cosa deve fare l'integrazione — leggere recensioni, aggiornare sedi, collegare un assistente AI — così da scegliere gli ambiti minimi.
Passaggi
- Apri Altro → API.
- In Chiavi API fai clic su Crea chiave.
- Inserisci un Nome chiaro che indichi dove viene usata la chiave, ad esempio
Production · backend. - Seleziona gli Ambiti di cui ha bisogno l'integrazione. Scegline il meno possibile. Per collegare un assistente AI tramite il server MCP, includi
mcp:connect. - Fai clic su Crea chiave nella finestra.
- La finestra Salva il tuo token mostra il token completo. È l'unica volta in cui viene mostrato. Copialo e conservalo in un luogo sicuro, come il tuo gestore di password o l'archivio dei segreti del tuo server.
- Fai clic su Fatto.
Importante: Tratta il token come una password. Non inserirlo mai nel codice di un sito web eseguito nei browser dei visitatori e non condividerlo mai via email o chat.
Verifica del risultato
Esegui una richiesta di prova con il token; il blocco Avvio rapido nella schermata API mostra un esempio:
curl https://<your cabinet address>/api/v1/locations \
-H "Authorization: Bearer <your token>"
Una risposta riuscita restituisce le tue sedi. Nella schermata API, la data di Ultimo utilizzo della chiave si aggiorna e la chiamata compare in Log delle richieste.
Ruotare o revocare una chiave
- Se il token potrebbe essere stato divulgato, o come normale buona pratica, usa Ruota nella riga della chiave. Il nuovo token viene mostrato una sola volta; quello vecchio smette subito di funzionare: aggiorna tutte le integrazioni che lo usano.
- Se la chiave non serve più, usa Revoca. Le chiamate con quella chiave non riescono più da subito. L'operazione non può essere annullata.
Risoluzione dei problemi
- "Il nome della chiave è obbligatorio" / "Scegli almeno un ambito". Compila il nome e seleziona almeno un ambito.
- Le richieste restituiscono 401. Il token è errato, incompleto, revocato o ruotato. Controlla l'intestazione
Authorization: Bearer …. - Le richieste restituiscono 403. Alla chiave manca un ambito richiesto dall'endpoint. Il riferimento API elenca gli ambiti richiesti per ogni endpoint; crea una chiave con gli ambiti corretti.
- Le richieste restituiscono 429. Hai superato il limite al minuto. Attendi il tempo indicato nell'intestazione
Retry-After. - Ho perso il token. Non può essere mostrato di nuovo. Ruota la chiave per ottenere un nuovo token.