Account
Chiavi API e Accesso Sviluppatore
Kapsule gives you two developer surfaces: scoped API keys for reading your account programmatically, and a remote build cache that speeds up Turborepo and Nx builds on your own machines and CI…
Chiavi API e Accesso per gli Sviluppatori
Kapsule ti fornisce due superfici per sviluppatori: chiavi API con ambito per leggere il tuo account a livello programmatico e una cache di build remota che accelera i build Turborepo e Nx sulle tue macchine e runner CI.
Nessuna delle due è abilitata per impostazione predefinita. Entrambe vengono create da Impostazioni e entrambe ti forniscono un segreto esattamente una volta.
Creazione di una Chiave API
Le chiavi API si trovano in Impostazioni, quindi Sicurezza, nella scheda API Keys.
- Vai a Impostazioni, quindi Sicurezza.
- Scorri fino a API Keys e fai clic su New key.
- Assegna un nome alla chiave. Il campo suggerisce "Key name (e.g. My automation script)". Il nome è solo per te, quindi sceglilo in base al luogo in cui verrà utilizzata la chiave.
- Fai clic sui chip di ambito per selezionare cosa può fare la chiave. Tre ambiti di lettura sono preselezionati:
read:sites,read:emaileread:domains. Fai clic su un chip per aggiungerlo o rimuoverlo. - Fai clic su Create.
La chiave completa appare una sola volta, in un pannello verde intestato "Copy now". Copiala direttamente nel tuo archivio di segreti. Quando chiudi quel pannello, la chiave è sparita: solo un breve prefisso viene conservato, che è tutto ciò che l'elenco potrà mostrarti ancora.
La chiave non viene mai visualizzata una seconda volta e non può essere recuperata. Se la perdi, revoca quella chiave e creane una nuova. Non incollarla in un documento condiviso, un ticket, un commit o un messaggio di chat.
Solo i ruoli Owner e Admin possono creare una chiave. Qualsiasi altro ruolo riceve un errore di permessi. Quando viene creata una chiave, un'email di avviso di sicurezza viene inviata all'indirizzo di chi l'ha creata, quindi una di quelle inaspettate merita di essere investigata immediatamente.
Gli Ambiti
Sono offerti sette ambiti:
| Ambito | Consente |
|---|---|
read:sites | Lettura dei tuoi siti web |
write:sites | Riservato per operazioni di scrittura sui siti web |
read:email | Lettura delle tue caselle di posta |
write:email | Riservato per operazioni di scrittura sulle caselle di posta |
read:domains | Lettura dei tuoi domini |
write:domains | Riservato per operazioni di scrittura sui domini |
read:billing | Riservato per la lettura dei dati di fatturazione |
L'API del cliente è attualmente di sola lettura. Gli ambiti write: e read:billing possono essere selezionati su una chiave, ma attualmente nessun endpoint del cliente li utilizza, quindi concederli non cambia nulla. Concedi solo gli ambiti di lettura che effettivamente hai bisogno e revisiona la chiave quando verranno rilasciati gli endpoint di scrittura.
Utilizzo di una Chiave
Invia la chiave come token bearer nell'header Authorization.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
Tre endpoint accettano una chiave API del cliente:
| Endpoint | Ambito richiesto | Restituisce |
|---|---|---|
GET /api/v1/sites | read:sites | I tuoi siti web, con dominio, tipo di applicazione e stato |
GET /api/v1/domains | read:domains | I tuoi domini, con stato e data di scadenza |
GET /api/v1/mailboxes | read:email | Le tue caselle di posta |
Una richiesta senza chiave, con una chiave sconosciuta o con una chiave revocata restituisce 401. Una chiave valida senza l'ambito corretto restituisce 403 con un messaggio che indica l'ambito necessario. Ogni chiamata riuscita aggiorna il timestamp dell'ultimo utilizzo della chiave.
Sondaggio delicato. Questi endpoint leggono i dati dell'account in tempo reale, e un ciclo stretto contro di loro è indistinguibile dall'abuso. Una volta al minuto è generoso per qualsiasi cosa un dashboard abbia bisogno; una volta all'ora è di solito più che sufficiente.
Revisione e Revoca delle Chiavi
La tabella API Keys elenca ogni chiave attiva per Nome, Prefisso (l'inizio visibile della chiave) e Ambiti. Fai clic su Revoke alla fine di una riga per disattivarla.
La revoca ha effetto immediato e non c'è una finestra di dialogo di conferma. La richiesta successiva utilizzando quella chiave non riesce con 401. Una chiave revocata non può essere ripristinata, quindi assicurati di sapere cosa la sta utilizzando prima di fare clic.
Le chiavi appartengono all'account, non alla persona che le ha create. Rimuovere un membro del team da la pagina Team non revoca le chiavi che hanno creato. Includi una revisione delle chiavi nel tuo offboarding: rimuovi la persona, quindi vieni qui e revoca tutto ciò che hanno creato.
La creazione e la revoca delle chiavi sono entrambe registrate nel registro di audit sotto le azioni api_key.*, con l'attore e l'indirizzo IP di origine.
La Cache di Build Remota
La pagina Developer, nel gruppo Avanzate della barra delle impostazioni, offre una Remote Build Cache. Il pannello la descrive come un modo per "Accelerare i build Turborepo e Nx condividendo una cache distribuita tra macchine e pipeline CI".
- Vai a Impostazioni, quindi Developer.
- Fai clic su Enable remote cache.
- Copia il token dal pannello intestato "New token generated. Copy it now, it won't be shown again".
Quindi imposta due variabili di ambiente nella tua configurazione CI o nel tuo .env.local locale:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
L'ID del team è il tuo ID account Kapsule, mostrato nelle istruzioni di configurazione sulla stessa pagina.
La pagina dichiara la sua stessa compatibilità: Turborepo 1.x e successivi, Nx 16 e successivi, e qualsiasi strumento che implementi lo stesso protocollo di cache remota. Gli artefatti vengono archiviati per account e non vengono mai condivisi tra account.
Due ulteriori controlli si trovano sulla scheda:
- Rotate token emette un nuovo token e invalida quello vecchio. Qualsiasi job CI che mantiene ancora il vecchio token smette di utilizzare la cache, quindi ruota e aggiorna i tuoi segreti insieme.
- Disable disattiva completamente la cache.
Scelta tra i Due
Risolvono problemi non correlati e non sono intercambiabili.
Usa una chiave API quando qualcosa al di fuori di Kapsule ha bisogno di conoscere lo stato del tuo account: una bacheca di stato che elenca i tuoi siti, uno script che ti avvisa della scadenza imminente dei domini, un'esportazione dell'inventario.
Usa la cache di build remota quando i tuoi build sono lenti perché ogni macchina e ogni esecuzione CI ricostruisce gli stessi pacchetti invariati. Non ha nulla a che fare con i tuoi siti ospitati e non legge i dati del tuo account.
Se stai distribuendo da Git anziché chiamare un'API, guarda invece Kapsule Orbit. Costruisce e spedisce direttamente dal tuo repository, con il caching di build gestito per te.
Risoluzione dei Problemi
Ogni richiesta restituisce 401. Conferma che hai inviato l'header come Authorization: Bearer <key> con un singolo spazio, che la chiave non sia stata troncata quando l'hai copiata e che non sia stata revocata. Confronta l'inizio della tua chiave con la colonna Prefisso per assicurarti di stare utilizzando la chiave che pensi di stare utilizzando.
Una richiesta restituisce 403 indicando un ambito. La chiave non ha quell'ambito. Gli ambiti sono fissi quando la chiave viene creata, quindi crea una sostituzione con gli ambiti corretti e revoca quella vecchia.
Non riesco a vedere la scheda API Keys. Si trova nella pagina Sicurezza, non nella pagina Developer. La pagina Developer contiene solo la cache di build.
Il pulsante New key non fa nulla. Il tuo ruolo è al di sotto di Admin. Chiedi all'Owner o a un Admin.
I build non stanno utilizzando la cache. Controlla che sia TURBO_TOKEN che TURBO_TEAM siano presenti nell'ambiente di build, che il token non sia stato ruotato da quando l'hai impostato, e che la pagina mostri ancora il badge Active.
Una chiave che non ho creato è apparsa. Trattala come un compromesso. Revocala, quindi esamina Account Security e controlla il registro di audit per vedere cos'altro è cambiato.