# Chiavi API e Accesso Sviluppatore

Source: https://support.kapsulehost.com/it-it/developer-api-access

KapsuleHost ti fornisce due superfici per sviluppatori: chiavi API scoped per leggere il tuo account a livello di programma, e una cache di build remota che accelera i build Turborepo e Nx sulle tue macchine e sui runner CI.

Nessuna delle due è abilitata per impostazione predefinita. Entrambe vengono create da **Impostazioni**, e entrambe ti consegnano un segreto esattamente una volta.

## Creazione di una Chiave API

Le chiavi API si trovano in **Impostazioni**, quindi **Sicurezza**, nella scheda **Chiavi API**.

![Scheda Chiavi API nelle impostazioni di sicurezza di KPanel con i chip di scope visibili](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp)

1. Vai a **Impostazioni**, quindi **Sicurezza**.
2. Scorri fino a **Chiavi API** e fai clic su **Nuova chiave**.
3. Assegna un nome alla chiave. Il campo suggerisce "Nome chiave (ad es. Il mio script di automazione)". Il nome è solo per te, quindi fai in modo che indichi dove verrà utilizzata la chiave.
4. Fai clic sui chip di scope per selezionare cosa la chiave può fare. Tre scope di lettura sono preselezionati: `read:sites`, `read:email` e `read:domains`. Fai clic su un chip per aggiungerlo o rimuoverlo.
5. Fai clic su **Crea**.

La chiave completa appare una volta sola, in un pannello verde intestato "Copia ora". Copiala direttamente nel tuo archivio segreti. Quando chiudi quel pannello la chiave è sparita: solo un breve prefisso viene conservato, che è tutto ciò che l'elenco potrà mai mostrarti di nuovo.

> **Warning:** 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 incollarlo in un documento condiviso, un ticket, un commit o un messaggio di chat.

Solo i ruoli **Proprietario** 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 riceverne una inaspettata vale la pena investigare immediatamente.

## Gli Scope

Vengono offerti sette scope:

| Scope | Concede |
|---|---|
| `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 |

> **Note:** L'API del cliente è di sola lettura oggi. Gli scope `write:` e `read:billing` possono essere selezionati su una chiave, ma nessun endpoint del cliente li consuma attualmente, quindi concederli non cambia nulla. Concedi solo gli scope di lettura che effettivamente necessiti e rivedi la chiave quando gli endpoint di scrittura saranno disponibili.

## Utilizzo di una Chiave

Invia la chiave come token bearer nell'intestazione `Authorization`.

```sh
curl https://kpanel.kapsulehost.com/api/v1/sites \
  -H "Authorization: Bearer YOUR_KEY_HERE"
```

Tre endpoint accettano una Chiave API cliente:

| Endpoint | Scope 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 scadenza |
| `GET /api/v1/mailboxes` | `read:email` | Le tue caselle di posta |

Una richiesta senza chiave, con una chiave sconosciuta o revocata restituisce `401`. Una chiave valida senza lo scope giusto restituisce `403` con un messaggio che nomina lo scope che era necessario. Ogni chiamata riuscita aggiorna il timestamp dell'ultimo utilizzo della chiave.

> **Tip:** Esegui il polling con gentilezza. Questi endpoint leggono dati account live, e un ciclo stretto contro di essi è indistinguibile dall'abuso. Una volta al minuto è generoso per qualsiasi cosa una dashboard abbia bisogno; una volta all'ora di solito è più che sufficiente.

## Revisione e Revoca delle Chiavi

La tabella Chiavi API elenca ogni chiave attiva per **Nome**, **Prefisso** (l'inizio visibile della chiave) e **Scope**. Fai clic su **Revoca** alla fine di una riga per disattivarla.

> **Important:** La revoca ha effetto immediato e non c'è alcuna finestra di dialogo di conferma. La prossima richiesta 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 collega da [la pagina Team](https://support.kapsulehost.com/it-it/account-team-members) non revoca le chiavi che hanno creato. Crea una revisione delle chiavi nel tuo offboarding: rimuovi la persona, poi vieni qui e revoca tutto ciò che hanno creato.

La creazione e la revoca delle chiavi sono entrambe registrate nel [registro di audit](https://support.kapsulehost.com/it-it/account-audit-log) sotto le azioni `api_key.*`, con l'attore e l'indirizzo IP di provenienza.

## La Cache di Build Remota

La pagina **Developer**, nel gruppo Advanced della barra delle impostazioni, offre una **Cache di build remota**. Il pannello la descrive come un modo per "Accelerare i build Turborepo e Nx condividendo una cache distribuita tra macchine e pipeline CI."

1. Vai a **Impostazioni**, quindi **Developer**.
2. Fai clic su **Abilita remote cache**.
3. Copia il token dal pannello intestato "Nuovo token generato. Copialo adesso, non verrà mostrato di nuovo".

Quindi imposta due variabili di ambiente nella tua configurazione CI o nel file `.env.local` locale:

```sh
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
```

L'ID del team è il tuo ID account KapsuleHost, mostrato nelle istruzioni di configurazione sulla stessa pagina.

La pagina indica la sua stessa compatibilità: Turborepo 1.x e successivo, Nx 16 e successivo, 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:

- **Ruota token** emette un nuovo token e invalida quello vecchio. Qualsiasi job CI che ancora possiede il vecchio token smette di usare la cache, quindi ruota e aggiorna i tuoi segreti insieme.
- **Disabilita** spegne 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 KapsuleHost ha bisogno di conoscere lo stato del tuo account: una bacheca di stato che elenca i tuoi siti, uno script che ti avverte dei domini in scadenza a breve, un'esportazione di 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 hosted e non legge i dati del tuo account.

## Risoluzione dei Problemi

**Ogni richiesta restituisce 401.** Conferma di aver inviato l'intestazione come `Authorization: Bearer <key>` con uno spazio singolo, 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 utilizzare.

**Una richiesta restituisce 403 nominando uno scope.** La chiave non possiede quello scope. Gli scope sono fissi quando la chiave viene creata, quindi crea una sostituzione con gli scope giusti e revoca quella vecchia.

**Non riesco a vedere la scheda Chiavi API.** Si trova nella pagina Sicurezza, non nella pagina Developer. La pagina Developer contiene solo la cache di build.

**Il pulsante Nuova chiave non fa nulla.** Il tuo ruolo è inferiore a Admin. Chiedi al Proprietario o a un Admin.

**I build non stanno utilizzando la cache.** Verifica 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 **Attivo**.

**Una chiave che non ho creato è apparsa.** Trattala come un compromesso. Revocala, quindi lavora su [Sicurezza Account](https://support.kapsulehost.com/it-it/account-security) e controlla il [registro di audit](https://support.kapsulehost.com/it-it/account-audit-log) per vedere cos'altro è cambiato.