Autenticazione
Ogni richiesta tranne il controllo di salute porta una chiave. Le chiavi identificano un'organizzazione anziché un utente, e portano con sé il piano e la quota di quell'organizzazione.
L'intestazione
curl -sS "https://api.skautik.com/v1/api/properties?city=Berlin" \
-H "X-API-Key: sk_live_9f21c4a70b8e…"
# Va bene anche Authorization: Bearer, per i client a cui risulta più comodo.
curl -sS "https://api.skautik.com/v1/api/properties?city=Berlin" \
-H "Authorization: Bearer sk_live_9f21c4a70b8e…"Va bene una qualsiasi delle due intestazioni. Se ci sono entrambe, vince X-API-Key. Un'intestazione assente o
malformata restituisce 401 con il codice authentication_required, e la
risposta non dice mai se la chiave non esiste o è stata revocata:
distinguerlo permetterebbe a qualcuno di sondare l'esistenza di chiavi valide.
Tipi di chiave
| Prefisso | Tipo | Cosa fa |
|---|---|---|
sk_live_ | Produzione | Legge e scrive il patrimonio reale. Limitata sulla quota del tuo piano. |
sk_test_ | Test | Legge un piccolo insieme di dati fisso e accetta scritture che vengono scartate. Gratuita e con limiti generosi, così i test di integrazione non bruciano quota. |
Il prefisso fa parte della chiave, quindi una stringa trapelata è riconoscibile come una credenziale Skautik in un log o in una scansione di repository. È voluto: gli scanner di segreti possono individuarla e avvisarti prima che la trovi qualcun altro.
Ambiti
Gli ambiti sono per risorsa e non una coppia generica di lettura e scrittura. Una chiave viene creata con l'insieme che le serve, e l'API rifiuta qualsiasi chiamata la cui chiave non abbia l'ambito richiesto da quella rotta.
Concedi l'insieme più stretto che faccia il lavoro. Una chiave emessa per l'analisi di mercato non può poi leggere i recapiti di nessuno né ritirare un annuncio, per quanto male possa trapelare.
| Ambito | Consente |
|---|---|
properties:read | Leggere gli immobili e i loro contenuti multimediali. |
properties:write | Creare, aggiornare e ritirare immobili. |
markets:read | Leggere statistiche e intelligenza di mercato. |
imports:write | Inviare e gestire importazioni massive. |
exports:create | Richiedere esportazioni e scaricarne i risultati. |
images:write | Generare e allegare immagini renderizzate. |
webhooks:manage | Creare, aggiornare ed eliminare endpoint webhook. |
inquiries:read | Leggere le richieste inviate sui tuoi immobili. |
Rotazione
Le chiavi non scadono a scadenza fissa, perché una scadenza forzata tende a produrre un disservizio più che maggiore sicurezza. Ruota piuttosto di proposito. Un'organizzazione può avere più chiavi contemporaneamente proprio perché questo non richieda alcuna interruzione:
- Crea una seconda chiave accanto a quella in uso.
- Distribuiscila ai tuoi servizi e verifica che il traffico si sia spostato su di essa.
- Controlla nella pagina delle chiavi che quella vecchia sia rimasta muta, invece di darlo per scontato.
- Revoca la chiave vecchia.
La revoca ha effetto immediato, senza periodo di grazia.
Tenere segreta una chiave
- Solo lato server. Una chiave consegnata a un browser o a un binario mobile è una chiave pubblicata, per quanto offuscata. Fai da proxy con il tuo backend.
- Tieni le chiavi in variabili d'ambiente o in un gestore di segreti, mai in un repository, in un artefatto di build o in un pacchetto lato client.
- Usa una chiave distinta per ambiente e per servizio, così revocarne una non fa cadere tutto il resto.
- La chiave completa viene mostrata una sola volta alla creazione e conservata solo come hash. Non possiamo recuperartela; creane una nuova.
Se una chiave trapela
Revocala prima e indaga dopo: una chiave revocata ti costa un rilascio, una trapelata e attiva ti costa la quota e i dati.
Poi scrivi a security@skautik.com così possiamo verificare un utilizzo che non hai fatto tu. Sorvegliamo anche i servizi pubblici di hosting del codice per i nostri prefissi di chiave e revocheremo una chiave che troviamo esposta, avvisandoti quando lo facciamo.
Verificare una chiave
GET /v1/api/me riporta l'organizzazione, il piano e la quota rimanente dietro una
chiave. È la chiamata giusta per un controllo all'avvio o per una sonda di salute, perché
dimostra che la chiave funziona senza paginare una risorsa.
Gestisci le chiavi dalla pagina delle chiavi API.