Una chiave API non è una password e non è un abbonamento. È una delega: un pezzo di testo che dice al nodo «chi lo presenta agisce per conto mio, entro questi limiti». Tutto quello che c'è da capire sulle chiavi sta in questa pagina.
Il tuo nodo, indirizzo /, con le tue credenziali. Se non hai un nodo
tuo, si installa in cinque minuti: le chiavi si generano
solo sul proprio, non si chiedono a nessuno.
Nel menù di sinistra. C'è l'elenco delle chiavi che hai già e il riquadro Genera nuova chiave.
Il nome serve solo a te, per ricordarti a cosa serve quando ne avrai otto.
I domini autorizzati sono l'elenco delle origini che possono usarla
da un browser. Se la usi solo da un programma o da curl,
lascia vuoto.
La spunta sola lettura. Se non ti serve che scriva, mettila: è la differenza fra una chiave che, se scappa, è un fastidio e una che, se scappa, è un problema.
Il segreto si vede una volta sola. Alla creazione il nodo te lo mostra e tu lo copi. Da quel momento in poi, nell'elenco, ne vedrai solo i primi caratteri: il nodo non conserva la chiave, conserva la sua impronta. Non è una scomodità: è il motivo per cui, se qualcuno ti ruba il file del database, non si porta via le chiavi. Se la perdi, se ne genera un'altra e si revoca la vecchia.
Risposta breve: quello che vede il suo intestatario, e nient'altro.
Ogni chiamata che tocca l'archivio comincia con la stessa domanda interna: di chi è questa chiave?. La risposta è un utente, e da quel momento la chiamata lavora dentro le cose di quell'utente. Non c'è un modo di dire «dammi le cartelle di tutti», perché quel modo non è stato scritto.
In pratica: se Marisa, che non è amministratrice, genera una chiave e la mette sul suo sito, quel sito mostrerà le cartelle di Marisa. Se sul medesimo nodo Giorgio fa lo stesso, il suo sito mostrerà le cartelle di Giorgio. Stesso indirizzo, stesso codice, stessa chiamata: cambia solo la chiave, e cambia tutto.
Con la chiave non si entra nel pannello, non si cambia la password, non si vedono le altre chiavi in chiaro. È una porta di servizio, non la porta di casa.
Dall'elenco, tasto Revoca. Da quel momento vale come se non fosse mai esistita, ovunque sia finita. Nessun periodo di grazia, nessuna cache.
Una per sito, una per script, una per la prova. Così quando una va buttata, si butta quella e non si rompe tutto il resto.
Una chiave marcata sola lettura risponde alle chiamate che leggono e rifiuta tutte le altre. Non «quasi tutte», non «le più pericolose»: tutte.
Il controllo è scritto in un punto solo,
prima ancora di guardare che chiamata sia. Se il verbo non è
GET o HEAD, la chiamata si ferma lì e torna
indietro con un 403. Non c'è un elenco di chiamate protette da
tenere aggiornato — e quindi non c'è il rischio che qualcuno,
aggiungendo una chiamata nuova, si dimentichi di metterla nell'elenco.
Questa è la ragione per cui il Portico può esistere. Tutta questa parte del sito parla al nodo vero, con dati veri, e i tasti «cancella» che trovi in giro sono chiamate autentiche: quello che le ferma non è una finta nel codice della pagina, è il nodo che dice di no.
Quando conviene. Un riquadro «ultimi arrivi» su un blog, un contatore, una pagina di stato, un albero di cartelle da sfogliare: tutta roba che legge. Se ti serve solo quello, non c'è nessun motivo di girare con una chiave che può cancellare. E se un domani ti serve, la spunta si toglie senza rigenerare niente.
Il posto dove tutti sbattono la testa la prima volta. Vale la pena capirlo una volta sola e poi non pensarci più.
I browser hanno una regola: una pagina
di sito-a.it non può leggere la risposta di
sito-b.it, a meno che sia sito-b.it a dire
esplicitamente «da sito-a.it mi va bene».
La lista dei domini autorizzati della chiave è esattamente quel
permesso. Il nodo la legge e risponde con l'intestazione che il browser aspetta.
Da curl,
da PowerShell, da Python, da un programma sul tuo server: il problema non esiste.
La regola è del browser, non del nodo. Chi lavora dal lato server può
lasciare il campo vuoto.
https://ilmiosito.it https://www.ilmiosito.it http://localhost:8080
Schema, dominio, eventuale porta. Separate da virgola. Una riga per origine.
ilmiosito.it https://ilmiosito.it/pagina.html https://*.ilmiosito.it
Manca lo schema; c'è un percorso di troppo; il carattere jolly non è previsto. Sono tre modi diversi di non funzionare.
Attenzione al www. https://sito.it e
https://www.sito.it sono due origini diverse per il browser, anche se
per te sono lo stesso sito. Se non sai da quale delle due arriveranno i tuoi
visitatori, mettile tutte e due. E ricorda http contro
https: stessa storia.
X-API-Key: xfsk_…
È il modo giusto. Le intestazioni non finiscono nella barra degli indirizzi, non finiscono nei registri dei proxy, non finiscono nei preferiti di nessuno.
?api_key=xfsk_…
Funziona, ed è l'unica strada per un tag <video> o per un
EventSource, che non sanno mandare intestazioni. Ma sappi che
l'indirizzo si vede e si copia. Per i video c'è di meglio:
il gettone legato al singolo file.
Ci sono due chiamate che
restituiscono un permesso ristretto e a tempo, da mettere tranquillamente in
un indirizzo pubblico:
• GET /fm/files/<id>/strm-token → vale solo per
riprodurre quel file;
• GET /fm/folders/<id>/download-token → vale solo per
scaricare quella cartella.
Se qualcuno li copia, con quelli non può fare nient'altro. È il modo
corretto di mettere roba dell'archivio su una pagina che vedono tutti.
Se la metti in una pagina web, è visibile. Chiunque apra il sorgente la legge. Questo non è un difetto da nascondere, è un fatto da tenere in conto, e infatti gli strumenti per tenerlo in conto ci sono tutti:
La regola pratica è semplice: se la chiave sta in una pagina, dev'essere in sola lettura e limitata al tuo dominio. Se deve scrivere, la chiamata falla dal tuo server, dove la chiave non la vede nessuno.