I permessi delle chiavi API decidono cosa può rompere una chiave trapelata. In un link tool, l'impostazione predefinita sicura è una chiave legata a un solo workspace, limitata al ruolo più basso che svolge il compito, conservata come hash con pepper, con un proprio rate limit e con una scadenza. Una chiave che crea solo link non ha motivo di toccare webhook, membri o fatturazione, e non dovrebbe mai aprire un endpoint admin. Questo è il privilegio minimo, e per la maggior parte dipende da scelte che fai nei trenta secondi necessari a creare la chiave.
Nell'ultimo anno ho letto molte configurazioni di automazione e lo schema si ripete: qualcuno incolla in n8n la propria chiave onnipotente un venerdì pomeriggio, funziona, e nessuno ci ripensa finché quella persona se ne va o l'export del workflow finisce in un drive condiviso. Il resto di questo articolo spiega come funzionano scope e ruoli delle chiavi API in un prodotto di link brevi, cosa può fare davvero ogni ruolo e come consegnare una chiave a uno strumento di automazione senza consegnare il workspace.
Si affianca alla nostra più ampia checklist di sicurezza per URL shortener, che copre scansione, firma dei webhook e audit log sull'intera piattaforma. Questo articolo si concentra sulla chiave stessa.
Cosa significano i permessi delle chiavi API in un link tool
L'API di un link tool tocca più dei soli link. Lo stesso token che crea go.example.com/spring-sale può, a seconda dei permessi, leggere le analytics dei click, aggiungere un dominio personalizzato, invitare un membro o registrare un webhook che invia ogni evento a un server esterno. Quest'ultimo mi spaventa. Un webhook è un flusso di dati permanente che chi lo crea può puntare a qualsiasi server voglia, e nessuno nel tuo team se ne accorgerebbe necessariamente per settimane.
Quindi i permessi hanno tre assi. Dove funziona la chiave (quale account o workspace)? Cosa può fare lì (leggere, scrivere, amministrare)? E per quanto tempo e a che velocità? La definizione del glossario NIST di least privilege (consultata il 2026-10-24) dice che a ogni entità vanno assegnate le autorizzazioni minime necessarie per svolgere la propria funzione, e tutti e tre gli assi ne fanno parte. Una chiave di sola lettura che non scade mai e non ha rate limit ha comunque troppi privilegi nel tempo.
Chiavi API legate al workspace: una chiave, un workspace
Su Elido ogni chiave viene generata dentro un workspace e lì resta. Se la usi per chiamare gli endpoint di un altro workspace ottieni un 404, la stessa risposta di un workspace che non esiste, quindi una chiave non può nemmeno confermare che gli altri workspace ci siano.
Conta più di quanto sembri. Agenzie e team più grandi appartengono spesso a cinque o dieci workspace. Se una chiave personale ereditasse tutto ciò che il suo creatore può raggiungere, un solo token trapelato da un progetto cliente aprirebbe tutti i clienti. Le chiavi API legate al workspace riducono il raggio d'azione a un solo workspace.
La chiave è inoltre limitata al ruolo scelto alla creazione e non supera mai il ruolo attuale del suo creatore. L'accesso effettivo è il più basso dei due. Declassa a editor l'admin che ha creato una chiave: la chiave scende con lui. Anche i permessi personalizzati assegnati a quel membro vengono scartati ogni volta che il ruolo della chiave è il più basso, perché descrivono la persona, non la chiave.
Chiavi API basate sui ruoli: cosa può fare ogni ruolo
Le chiavi di Elido usano gli stessi quattro ruoli delle persone: viewer, editor, admin e owner. Ne scegli uno quando crei la chiave; se lo ometti, la chiave è editor per impostazione predefinita, che copre il tipico compito di automazione di creare link e leggere le analytics senza alcuna portata da admin.
Ecco come si traduce in pratica per le cose che le integrazioni toccano di solito.
| Ruolo | Link e campagne | Analytics | Webhook | Domini, membri, chiavi |
|---|---|---|---|---|
| viewer | Sola lettura | Lettura, avvio di job di export CSV | Elenco degli endpoint | Vede domini e membri |
| editor | Crea, modifica, elimina, creazione massiva | Lettura, avvio di job di export CSV | Elenco degli endpoint | Vede domini e membri |
| admin | Tutto ciò che può fare editor | In più configurazione dell'export dati su S3, report email pianificati | Crea, modifica, riesegue | Gestisce domini, membri, chiavi |
| owner | Tutto | Tutto | Tutto | Tutto |
Una dashboard di reporting che porta i conteggi dei click in uno strumento di BI richiede viewer. Un job su Google Sheets che genera link di campagna richiede editor. Quasi nulla nell'automazione quotidiana richiede admin, e considererei una chiave owner un cattivo segnale: owner esiste per le persone che gestiscono il workspace, e non mi viene in mente alcun compito di automazione che la richieda.
Vale la pena conoscere due limiti. Solo admin e owner hanno il permesso api_keys.manage, quindi una chiave viewer o editor non può elencare né revocare le chiavi. E creare una chiave, o cambiarne il rate limit, richiede una persona con accesso effettuato: una chiave API di qualsiasi ruolo riceve un 403 ("this action requires an interactive session"). Una chiave admin trapelata non può generare una sostituta senza scadenza. Può comunque elencare e revocare le chiavi. E nessuna chiave di alcun ruolo raggiunge l'API admin della piattaforma. Quella superficie rifiuta del tutto l'autenticazione con chiave API con un 403 e il messaggio "admin access requires an interactive session". Una chiave serve a un'integrazione del workspace, ed è tutto ciò che apre.
Perché la gestione dei webhook richiede una chiave admin
È la cosa che sorprende le persone. Leggere l'elenco degli endpoint webhook è consentito a qualsiasi membro, chiavi viewer comprese. Ma creare un endpoint, cambiarne la destinazione o rieseguire una consegna richiede il permesso workspace.edit, che hanno solo admin e owner.
Il ragionamento è il problema del flusso permanente di cui sopra. Un editor può creare mille link e te ne accorgi. Un editor che potesse aggiungere un webhook catch-all puntato al proprio server riceverebbe da allora in poi ogni evento dei link, in silenzio. Quindi le modifiche ai webhook spettano alle stesse persone che possono cambiare le impostazioni del workspace.
In pratica, configura i webhook una sola volta, a mano, come admin nella dashboard. Poi dai all'automazione che li consuma una chiave editor o viewer per le sue chiamate API. Se stai collegando webhook per gli eventi dei link a Slack o a un CRM, il lato ricevente non ha affatto bisogno di una chiave Elido; gli serve il segreto di firma per verificare i payload.
Vuoi una prova prima di collegare qualsiasi cosa? Crea un workspace gratuito, genera una chiave viewer e una editor e prova la stessa chiamata di scrittura con ciascuna. Il 403 sulla chiave viewer ti dice più di qualsiasi tabella.
Come sono conservate le chiavi: pepper, hash e prefisso
Un token ha la forma elido_ seguito da 52 caratteri in base32, generati da 32 byte casuali. Lo vedi per intero una sola volta, nella risposta alla chiamata di creazione. Dopo, dal nostro lato sparisce per sempre.
Quello che conserviamo è un HMAC-SHA256 del token, con una chiave pepper lato server che sta nella configurazione dell'applicazione, non nel database. A ogni richiesta il token Bearer in arrivo (lo schema definito nella RFC 6750, consultata il 2026-10-24) viene sottoposto allo stesso hash e cercato per hash. Quindi un dump rubato del database è un elenco di hash che nessuno può verificare senza il pepper. Senza pepper, niente avvio: il servizio di produzione rifiuta di partire se non ne è impostato uno.
Per i vostri registri conserviamo i primi otto caratteri dopo elido_ come prefisso di visualizzazione, e la pagina delle chiavi API mostra quel prefisso accanto al nome della chiave, al ruolo, alla data di creazione, alla scadenza, all'ultimo utilizzo e all'ultimo IP utilizzato, oltre ai conteggi totali e falliti delle richieste. Quando una chiave salta fuori in un log da qualche parte, il prefisso vi dice di quale si tratta. Nessuno deve vedere il segreto completo.
Rate limit, scadenza e rotazione delle chiavi API
Ogni chiave ha un proprio token bucket, separato dal limite per workspace, così un workflow fuori controllo non può consumare il budget di tutto il resto. Un admin con accesso effettuato può sovrascrivere il rate di una singola chiave da 1 a 10.000 richieste al secondo e il burst da 1 a 20.000, oppure rimuovere la sovrascrittura per tornare al valore predefinito. Oltre il limite, la chiave riceve un 429 con Retry-After: 1 e X-RateLimit-Scope: api_key, così la tua logica di retry può distinguere il tetto di una chiave da quello di un workspace. La guida a rate limit e idempotenza spiega come fare un backoff corretto.
La scadenza è facoltativa e si imposta alla creazione come timestamp RFC 3339. Una volta superata, la chiave semplicemente smette di corrispondere. La revoca è una sola DELETE. Ed è anche idempotente.
Non esiste un unico pulsante "ruota", e non lo rimpiango. La rotazione è in tre passaggi:
- Crea una nuova chiave con lo stesso ruolo e una nuova scadenza.
- Inseriscila nel credential store dello strumento e verifica che una chiamata riesca.
- Revoca la vecchia chiave, poi controlla nell'elenco che l'ora del suo ultimo utilizzo non si muova più.
Ogni passaggio finisce nell'audit log del workspace: api_key.created con nome e ruolo, api_key.revoked e api_key.rate_limit_set per le sovrascritture. Una scansione in background gira inoltre ogni cinque minuti e segnala ogni chiave con più di 1.000 richieste di cui oltre il 30% fallite. Il flag va nell'audit log e sulla chiave. Nessuna revoca automatica. Eliminare una chiave è una decisione umana, perché un'ondata di 404 è spesso un workflow rotto quanto un attaccante.
Consegnare chiavi API a privilegio minimo a n8n, Make e Zapier
Le piattaforme di automazione sono il posto in cui le chiavi vanno per essere dimenticate. Restano in un credential store, vengono copiate nel JSON esportato dei workflow e sopravvivono alla persona che le ha configurate. Due abitudini aiutano:
- Una chiave per strumento e per famiglia di workflow, con il nome dello strumento ("n8n: campaign sheets"). Revocarla rompe allora esattamente una cosa, e l'audit log dice quale strumento ha fatto cosa.
- Editor per tutto ciò che crea link, viewer per tutto ciò che si limita a leggere, e una data di scadenza su entrambi.
Per l'elenco è tutto; il resto è giudizio. La Secrets Management Cheat Sheet di OWASP (consultata il 2026-10-24) è una buona lettura per tenere i token fuori da log ed export, che è di solito dove le chiavi di automazione trapelano.
Per la configurazione specifica di ogni strumento, la guida all'URL shortener per n8n mette la chiave in una credenziale Header Auth, e il confronto tra Make, IFTTT, n8n e Zapier spiega dove la conserva ciascuna piattaforma. Zapier si collega con lo stesso token, come nella guida all'automazione con Zapier. Per la CI o per qualsiasi cosa debba sopravvivere all'uscita di una persona, è più adatto un machine user: un service account con un proprio token, separato dalla chiave di qualsiasi persona. Come le chiavi, i machine user li crea un admin con accesso effettuato, mai un token.
E il motivo per cui una chiave non deve mai aprire gli endpoint admin è proprio questa consegna. Quando un token sta in uno strumento di terze parti, chiunque abbia accesso in modifica ai workflow di quello strumento può usarlo. Ti fidi di tutti dal loro lato, non solo dei tuoi.
I token per singolo scope sono pianificati, non attivi
I ruoli sono grossolani di proposito, e a volte troppo. Una chiave editor che crea solo link può anche eliminarli, perché eliminare fa parte del ruolo editor. La soluzione sono i token per singolo scope, come links:write o analytics:read associati direttamente a una chiave, sovrapposti ai ruoli.
È nella nostra roadmap e non è stato rilasciato. Oggi i permessi di una chiave sono il suo workspace più il suo ruolo, e niente di più fine. Se ti serve un controllo più stretto adesso, le due leve sono un ruolo più basso e una scadenza breve, più chiavi separate per compito, così il raggio d'azione di ciascuna è ridotto. Il quickstart dell'API e il riferimento API e SDK mostrano in codice funzionante il modello di chiavi attuale, e i team che vogliono anche un controllo a livello di identità possono leggere SCIM e SSO per gli strumenti di marketing.
Leggi il cornerstone: la checklist di sicurezza per URL shortener copre i controlli intorno alla chiave, dalla scansione degli URL alle allowlist IP.
Correlati sul blog
Domande frequenti
Cosa sono i permessi delle chiavi API?
Sono l'insieme delle azioni che una chiave può compiere su un'API: quali risorse può leggere, quali può modificare e in quale account. In Elido i permessi di una chiave derivano dal workspace in cui è stata emessa e dal ruolo scelto alla creazione, quindi la stessa chiave non può agire in un altro workspace né sopra quel ruolo.
Cos'è il privilegio minimo per le chiavi API?
Significa che ogni chiave riceve il più piccolo insieme di permessi necessario al suo compito e nulla di più. Una dashboard che legge solo i conteggi dei click riceve una chiave viewer, un workflow che crea link riceve una chiave editor e le chiavi admin sono riservate al raro compito che gestisce webhook, domini o membri. Una chiave trapelata può così fare solo ciò che faceva quel singolo compito.
Qual è la differenza tra scope e ruoli delle chiavi API?
Uno scope è un permesso ristretto come links:write associato direttamente a un token, mentre un ruolo è un pacchetto di permessi con un nome, come editor. I ruoli sono più facili da ragionare; gli scope sono più fini. Le chiavi di Elido usano oggi i ruoli del workspace, e i token per singolo scope sono pianificati sopra di essi ma non ancora attivi.
Ogni quanto vanno ruotate le chiavi API?
L'indicazione comune è ogni 30-90 giorni, e subito ogni volta che se ne va qualcuno che ha visto la chiave, la chiave compare in un log o il suo traffico sembra anomalo. Impostare una data di scadenza alla creazione trasforma quel calendario in un arresto netto invece che in un promemoria che le persone ignorano.
Una chiave API può accedere agli endpoint admin?
Su Elido no. L'API admin della piattaforma accetta solo una sessione interattiva con accesso effettuato e firmata, e risponde a una chiave API con un 403, qualunque sia il ruolo di chi l'ha creata. Le impostazioni del workspace che richiedono diritti di admin restano raggiungibili, ma solo da una chiave creata con il ruolo admin o owner.
Come dovrebbe il provider conservare le chiavi API?
Mai in chiaro. Il provider dovrebbe conservare un hash con chiave del token e mostrarti poi solo un breve prefisso, così una copia del solo database non può essere usata per chiamare l'API. Elido calcola l'hash di ogni token con HMAC-SHA256 e un pepper lato server e mostra il token completo una sola volta.
Prova Elido
Incolla un URL, ottieni un link breve
Senza registrazione. Il link vive 30 giorni. Iscriviti per conservarlo.
Senza registrazione. Crea un account gratuito per 50 link al mese.