Crea una chiave API nella dashboard, scegli gli scope, scambiala con un token da 15 minuti, custodiscila al sicuro e revocala quando serve, passo dopo passo.
Una chiave API è il modo in cui i tuoi programmi accedono all’API di LinkHarbor. Appartiene a un workspace, non a una persona, e può fare esattamente ciò che le consenti tramite gli scope. Per le chiamate vere e proprie scambi la chiave con un token di accesso di breve durata.
Chi può creare chiavi API?
- Proprietari e admin del workspace – editor e visualizzatori vedono solo la scheda «App collegate» in «Callback e API»
- Da Creator Pro; in Creator Free la scheda indica «Le chiavi API sono disponibili a partire da Creator Pro.»
- Attive contemporaneamente: fino a 5 chiavi in Creator Pro, fino a 20 in Creator Agency, fino a 50 in Enterprise
Una volta raggiunto il limite, la creazione di una chiave fallisce con 409 limit_reached. Prima elimina una chiave che non ti serve più.
Creare una chiave API
- Apri «Callback e API» nella navigazione
- Nella scheda «Chiavi API» clicca su «+ Crea nuova chiave»
- In «Nome (facoltativo)» inserisci un nome con cui riconoscerai la chiave in seguito, per esempio «Pipeline CI/CD» o «Sincronizzazione shop»
- In «Scope» scegli «Lettura» o «Scrittura» per ogni area
- Clicca su «Crea chiave»
- Copia subito il «Secret della chiave (privato)» e conservalo in un posto sicuro
- Chiudi la finestra di dialogo – l’ID della chiave lo trovi sempre nell’elenco
- «Nome (facoltativo)»
- Fino a 64 caratteri. Senza nome, la chiave compare nell’elenco come «Chiave API #ID».
- «Scope»
- Ne serve almeno uno. «Scrittura» include automaticamente «Lettura» per la stessa area. Statistiche e pagamenti dei sostenitori sono in sola lettura, i modelli del workspace in sola scrittura. Tutti gli scope sono spiegati in Scope nel dettaglio.
- «Secret della chiave (privato)»
- Inizia con lt_ e viene mostrato una sola volta («⚠️ Visibile una sola volta — copialo ora!»). LinkHarbor ne salva solo un hash e non può mostrartelo di nuovo in seguito.
- «ID chiave:»
- 16 caratteri composti da cifre e dalle lettere maiuscole A–F, per esempio 6F668EA6598B0692. Non è segreto e compare nell’elenco con un pulsante per copiarlo.
L’elenco delle chiavi
Ogni chiave attiva mostra il nome, lo stato «Attivo», l’ID della chiave, i suoi scope, «Creata:» e «Ultimo utilizzo:» oppure «Non ancora utilizzata». L’ora dell’ultimo utilizzo viene aggiornata a ogni chiamata fatta con la chiave, al massimo una volta al minuto. «↺ Aggiorna» ricarica l’elenco.
Scambiare la chiave con un token di accesso
curl -X POST https://dock.at-harbor.com/v1/token \
-H "Content-Type: application/json" \
-d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }- token
- Il token di accesso. Lo invii con ogni richiesta come Authorization: Bearer <token>.
- expires_in
- Validità in secondi: 900, cioè 15 minuti. Non esiste un refresh token – quando scade, richiedi semplicemente un nuovo token con ID e secret della chiave.
Il token rappresenta il workspace e porta esattamente gli scope della chiave. Non ha un ruolo come una persona: gli endpoint che la dashboard riserva a proprietari e admin (membri, fatturazione, gestione dei domini, webhook, impostazioni del workspace) vengono sempre rifiutati per i token delle chiavi API. Fanno eccezione i link brevi e i modelli del workspace, che funzionano con lo scope corrispondente, e la lettura dei secret di callback (senza il secret in chiaro) con read:workspaces.
Tentativi falliti e blocco
| Situazione | Risposta |
|---|---|
| ID o secret della chiave errati, oppure chiave eliminata | 401 invalid_api_key |
| 5 tentativi falliti per un ID chiave dallo stesso IP | 429 api_key_locked, bloccata per 60 secondi |
| 10 tentativi falliti | 429 api_key_locked, bloccata per 5 minuti |
| 20 tentativi falliti | 429 api_key_locked, bloccata per 30 minuti |
| 50 tentativi falliti da un IP entro 10 minuti | 429 rate_limited, IP bloccato per 1 ora |
Con api_key_locked, il tempo rimanente è in details.retry_after_sec. Uno scambio riuscito azzera il contatore.
Eliminare e sostituire una chiave
- Clicca su «Elimina» accanto alla chiave
- Digita DELETE per confermare
- Clicca su «Elimina definitivamente»
La chiave smette subito di funzionare – anche i token di accesso già emessi smettono di funzionare da quel momento e ricevono 401 invalid_token. Non c’è un pulsante per ruotarla. Per cambiare chiave, creane una nuova, sposta il tuo programma su di essa e poi elimina quella vecchia.
Quando il piano scende
Se il workspace passa a Creator Free, tutte le chiavi API vengono revocate. Se passa a un piano con meno chiavi, vengono mantenute le più recenti e le altre vengono revocate. Le chiavi revocate non tornano dopo un successivo aggiornamento del piano – in quel caso ne crei di nuove. I proprietari ricevono un’e-mail con l’elenco delle funzioni disattivate. Altro in Disdetta, piano inferiore e pagamenti falliti.
Custodirla al sicuro
- Conserva il secret solo in un gestore di secret o in variabili d’ambiente, mai nel codice sorgente o in un repository Git
- Non usarlo mai in codice che gira nel browser o in un’app sul dispositivo dell’utente
- Crea una chiave separata per ogni applicazione, con il minor numero possibile di scope
- Elimina subito le chiavi che non ti servono più
- Se sospetti una fuga di dati: elimina la chiave e creane una nuova
Potrebbe esserti utile anche
Non hai trovato nulla?
Dicci di cosa hai bisogno e il nostro team di assistenza ti aiuterà personalmente.