I permessi delle chiavi API stabiliscono quali danni può causare una chiave sottratta. In uno strumento di link, l'impostazione sicura predefinita è una chiave vincolata a un solo workspace, limitata al ruolo minimo necessario, archiviata come hash con pepper, sottoposta a un limite di frequenza autonomo e impostata per scadere. 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 gran parte di esso dipende dalle scelte che fai nei trenta secondi necessari per creare la chiave.
Nell'ultimo anno ho esaminato molte configurazioni di automazione e lo schema si ripete: qualcuno incolla la propria chiave onnipotente in n8n un venerdì pomeriggio, funziona e nessuno ci pensa più finché quella persona non se ne va o l'esportazione del flusso di lavoro finisce in un'unità condivisa. Il resto di questo articolo spiega come funzionano ambiti e ruoli delle chiavi API in un prodotto di link brevi, cosa può davvero fare ogni ruolo e come consegnare una chiave a uno strumento di automazione senza consegnargli il workspace.
Si affianca alla nostra più ampia checklist di sicurezza per accorciatori URL, che tratta scansione, firma dei webhook e log di audit per l'intera piattaforma. Questo articolo si concentra sulla chiave stessa.
Cosa significano i permessi delle chiavi API in uno strumento di link
L'API di uno strumento di link fa più che gestire link. Lo stesso token che crea go.example.com/spring-sale può, in base ai suoi permessi, leggere le analisi dei clic, aggiungere un dominio personalizzato, invitare un membro o registrare un webhook che invia ogni evento a un server esterno. Quest'ultima possibilità mi preoccupa. Un webhook è un flusso di dati permanente che chi lo crea può indirizzare a qualsiasi server desideri, e nessuno del tuo team lo noterebbe necessariamente per settimane.
I permessi hanno quindi tre assi. Dove funziona la chiave, cioè in quale account o workspace? Cosa può fare lì, cioè leggere, scrivere o amministrare? E per quanto tempo e a quale velocità? La definizione NIST del privilegio minimo si riduce a concedere soltanto l'accesso necessario a un'attività, e tutti e tre gli assi ne fanno parte. Una chiave con diritti di sola lettura che non scade mai e non ha un limite di frequenza è comunque sovraprivilegiata nel tempo.
Chiavi API limitate al workspace: una chiave, un workspace
In Elido, ogni chiave viene emessa all'interno di un workspace e rimane lì. Se chiami gli endpoint di qualsiasi altro workspace con essa, ricevi un 404, la stessa risposta di un workspace inesistente, perciò una chiave non può nemmeno confermare che esistano altri workspace.
Questo conta più di quanto sembri. Le agenzie e i team più grandi appartengono spesso a cinque o dieci workspace. Se una chiave personale ereditasse tutto ciò a cui può accedere il suo creatore, un token sottratto da un progetto di un cliente aprirebbe l'accesso a tutti i clienti. Le chiavi API limitate al workspace riducono il raggio d'azione a un solo workspace.
La chiave è inoltre limitata al ruolo scelto al momento della creazione e non supera mai il ruolo attuale del suo creatore. L'accesso effettivo è il minore dei due. Declassa ad editor l'admin che ha creato una chiave e la chiave si riduce con lui. Anche i permessi personalizzati associati a quel membro vengono rimossi ogni volta che il ruolo della chiave è quello inferiore, perché descrivono la persona, non la chiave.
Chiavi API basate sui ruoli: cosa può fare ogni ruolo
Le chiavi 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 assume per impostazione predefinita il ruolo editor, che copre il normale lavoro di automazione di creazione dei link e lettura delle analisi senza privilegi admin.
Ecco come si presenta in pratica per gli elementi che di solito riguardano le integrazioni.
| Ruolo | Link e campagne | Analisi | Webhook | Domini, membri, chiavi |
|---|---|---|---|---|
| viewer | Sola lettura | Lettura, esecuzione esportazioni CSV | Elenco endpoint | Visualizza domini e membri |
| editor | Crea, modifica, elimina, crea in massa | Lettura, esecuzione esportazioni CSV | Elenco endpoint | Visualizza domini e membri |
| admin | Tutto ciò che può fare editor | Più esportazioni dati, report programmati | Crea, modifica, ripeti invio | Gestisce domini, membri, chiavi |
| owner | Tutto | Tutto | Tutto | Tutto |
Una dashboard di reportistica che trasferisce i conteggi dei clic in uno strumento BI necessita di viewer. Un'attività Google Sheets che genera link per le campagne necessita di editor. Quasi nulla nell'automazione quotidiana richiede admin e considererei una chiave owner un segnale sospetto: owner esiste per le persone che gestiscono il workspace e non mi viene in mente alcun lavoro di automazione che ne abbia bisogno.
Vale la pena conoscere due limiti. Solo admin e owner possono creare, elencare o revocare chiavi, quindi una chiave viewer o editor non può generarsi una sorella più potente. E nessuna chiave, di qualsiasi ruolo, raggiunge l'API admin della piattaforma. Questa superficie rifiuta del tutto l'autenticazione tramite 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
Questo è l'aspetto che sorprende le persone. Leggere l'elenco degli endpoint webhook è consentito a qualsiasi membro, incluse le chiavi viewer. Ma creare un endpoint, modificare la sua destinazione o ripetere una consegna richiede il permesso workspace.edit, che possiedono solo admin e owner.
Il ragionamento è il problema del flusso permanente menzionato prima. Un editor può creare mille link e te ne accorgerai. Un editor che potesse aggiungere un webhook globale indirizzato al proprio server riceverebbe silenziosamente ogni evento di link da quel momento in poi. Perciò le modifiche ai webhook sono affidate alle stesse persone che possono modificare le impostazioni del workspace.
In pratica, configura i webhook una sola volta, manualmente, come admin nel pannello. Poi assegna all'automazione che li utilizza una chiave editor o viewer per le sue chiamate API. Se stai collegando i webhook per eventi di 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 tutto? Crea un workspace gratuito, genera una chiave viewer e una chiave editor e prova la stessa chiamata di scrittura con entrambe. Il 403 della chiave viewer dice più di qualsiasi tabella.
Come sono archiviate le chiavi: pepper, hash e prefisso
Un token è formato da elido_ seguito da 52 caratteri base32, generati da 32 byte casuali. Lo vedi per intero esattamente una volta, nella risposta alla chiamata di creazione. Dopo, per noi è definitivamente sparito.
Ciò che conserviamo è un HMAC-SHA256 del token, con chiave costituita da un pepper lato server che risiede nella configurazione dell'applicazione, non nel database. A ogni richiesta il token Bearer in arrivo, cioè lo schema definito in RFC 6750, viene sottoposto allo stesso hash e cercato tramite hash. Un dump del database sottratto è un elenco di hash che non può essere verificato senza il pepper e il servizio di produzione rifiuta di avviarsi se non ne è impostato uno.
Per i tuoi archivi conserviamo come prefisso di visualizzazione i primi otto caratteri dopo elido_. La pagina delle chiavi API mostra quel prefisso accanto al nome, ruolo, data di creazione, scadenza, ultimo utilizzo e ultimo IP utilizzato della chiave, oltre ai conteggi delle richieste totali e non riuscite. Quando una chiave compare in un log, il prefisso indica quale sia senza che nessuno debba vedere il segreto completo.
Limiti di frequenza, scadenza e rotazione delle chiavi API
Ogni chiave riceve il proprio token bucket, separato dal limite per workspace, così un flusso di lavoro fuori controllo non può consumare il budget di tutto il resto. Un admin può impostare per una singola chiave una frequenza personalizzata da 1 a 10.000 richieste al secondo e una capacità di picco da 1 a 20.000, oppure rimuovere l'impostazione 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 logica di ripetizione può distinguere un limite della chiave da uno del workspace. La guida ai limiti di frequenza e all'idempotenza spiega come ridurre correttamente il ritmo.
La scadenza è facoltativa e viene impostata alla creazione come timestamp RFC 3339. Una volta superata, la chiave semplicemente smette di corrispondere. La revoca richiede un solo DELETE. È anche idempotente.
Non esiste un unico pulsante "ruota", e non mi manca. La rotazione richiede tre passaggi:
- Crea una nuova chiave con lo stesso ruolo e una nuova scadenza.
- Sostituiscila nell'archivio delle credenziali dello strumento e conferma che una chiamata riesca.
- Revoca la vecchia chiave, poi controlla nell'elenco che il suo ultimo utilizzo abbia smesso di aggiornarsi.
Ogni passaggio finisce nel log di audit del workspace: api_key.created con nome e ruolo, api_key.revoked e api_key.rate_limit_set per i limiti personalizzati. Ogni cinque minuti viene eseguita anche una scansione in secondo piano che segnala qualsiasi chiave con oltre 1.000 richieste di cui più del 30% non riuscite. Il contrassegno entra nel log di audit e compare sulla chiave. Nessuna revoca automatica. Disattivare una chiave è una decisione umana, perché un picco di 404 indica un flusso di lavoro rotto tanto spesso quanto un aggressore.
Consegnare chiavi API con privilegio minimo a n8n, Make e Zapier
Le piattaforme di automazione sono i luoghi in cui le chiavi vengono dimenticate. Restano in un archivio delle credenziali, vengono copiate nei JSON dei flussi di lavoro esportati e sopravvivono alla persona che le ha configurate. Due abitudini aiutano:
- Una chiave per strumento e per famiglia di flussi di lavoro, con un nome che la descriva ("n8n: fogli campagne"). Revocarla interrompe quindi esattamente una cosa e il log di audit indica quale strumento ha fatto cosa.
- Editor per tutto ciò che crea link, viewer per tutto ciò che legge soltanto e una data di scadenza per entrambi.
Questo è tutto per l'elenco; il resto richiede giudizio. Il promemoria OWASP sulla gestione dei segreti è una buona lettura su come tenere i token fuori da log ed esportazioni, che sono i luoghi in cui le chiavi di automazione di solito vengono esposte.
Per la configurazione specifica dello strumento, la guida all'accorciatore URL per n8n inserisce la chiave in una credenziale Header Auth e il confronto tra Make, IFTTT, n8n e Zapier spiega dove ogni piattaforma la conserva. Zapier si collega tramite lo stesso token, come indicato nella guida pratica all'automazione Zapier. Per CI o qualsiasi soluzione che debba sopravvivere all'uscita di una persona, un utente macchina è più adatto: un account di servizio con il proprio ruolo, separato dalla chiave di qualsiasi persona.
Ed è proprio questo passaggio il motivo per cui una chiave non deve mai aprire endpoint admin. Quando un token si trova in uno strumento di terze parti, chiunque disponga dell'accesso di modifica ai flussi di lavoro di quello strumento può usarlo. Ti fidi di tutti sul loro lato, non soltanto sul tuo.
I token per singolo ambito sono pianificati, non disponibili
I ruoli sono volutamente ampi e talvolta troppo ampi. Una chiave editor che crea soltanto link può anche eliminarli, perché l'eliminazione fa parte del ruolo editor. La soluzione sono token per singolo ambito, come links:write o analytics:read associati direttamente a una chiave e 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ù granulare. Se ora ti serve un controllo più rigoroso, le due leve sono un ruolo inferiore e una scadenza breve, oltre a chiavi separate per ogni attività così che il raggio d'azione di ciascuna rimanga ridotto. L'avvio rapido dell'API e il riferimento API e SDK mostrano il modello attuale delle chiavi in codice funzionante, e i team che desiderano anche un controllo a livello di identità possono leggere di SCIM e SSO per gli strumenti di marketing.
Leggi l'articolo fondamentale: la checklist di sicurezza per accorciatori URL tratta i controlli attorno alla chiave, dalla scansione URL alle liste di IP consentiti.
Articoli correlati sul blog
Domande frequenti
Cosa sono i permessi delle chiavi API?
Sono l'insieme delle azioni che una chiave può eseguire tramite 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 al momento della creazione, quindi la stessa chiave non può agire in un altro workspace né superare quel ruolo.
Che cos'è il privilegio minimo per le chiavi API?
Significa che ogni chiave riceve l'insieme minimo di permessi necessario al proprio compito e nulla di più. Un pannello che legge solo i conteggi dei clic riceve una chiave viewer, un flusso di lavoro che crea link riceve una chiave editor e le chiavi admin restano per le rare attività che gestiscono webhook, domini o membri. Una chiave sottratta può quindi fare solo ciò che faceva quel singolo compito.
Qual è la differenza tra ambiti e ruoli delle chiavi API?
Un ambito è 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 comprendere; gli ambiti sono più granulari. Oggi le chiavi Elido usano i ruoli del workspace e i token per singolo ambito sono pianificati sopra di essi, ma non sono ancora disponibili.
Con quale frequenza dovrebbero essere ruotate le chiavi API?
Le indicazioni comuni parlano di ogni 30-90 giorni, oltre che immediatamente quando lascia l'azienda una persona 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 programma in un blocco definitivo invece che in un promemoria del calendario 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 autenticata e risponde a una chiave API con un 403, indipendentemente dal ruolo della persona che l'ha creata. Le impostazioni del workspace che richiedono diritti admin sono comunque raggiungibili, ma solo da una chiave creata con il ruolo admin o owner.
Come dovrebbero essere archiviate le chiavi API dal lato del fornitore?
Mai in testo semplice. Il fornitore dovrebbe archiviare un hash con chiave del token e mostrarti in seguito 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.
Gratis, nessuna registrazione richiesta · 2 al giorno