Creare e gestire le chiavi API
Una chiave API è ciò che permette a uno strumento, uno script o un assistente IA di agire per conto della tua organizzazione. Le chiavi vengono create e gestite dentro Samsa da proprietari e admin.
Dove trovare le chiavi API
Apri Impostazioni organizzazione > Chiavi API. Solo i proprietari e gli admin dell'organizzazione possono gestire le chiavi — se non vedi la scheda, chiedi l'accesso a un admin.
Creare una chiave
Vai su Impostazioni organizzazione > Chiavi API e clicca su Crea chiave API.
Dai alla chiave un nome che riconoscerai in seguito — per esempio "pipeline CI" o "Zapier".
Scegli gli scope (permessi) che la chiave deve avere — prendi solo ciò che le serve (vedi sotto).
Imposta quando la chiave scade — 30 giorni, 90 giorni, 1 anno, Mai o una data personalizzata.
Clicca su Crea chiave.
Copia subito la tua chiave. Samsa mostra la chiave completa una sola volta, in una finestra intitolata "La tua nuova chiave API". Per motivi di sicurezza viene conservato solo un hash — se perdi la chiave non puoi recuperarla e dovrai crearne una nuova. Incollala direttamente nel tuo strumento o in un secrets manager sicuro, poi conferma "Ho salvato la chiave in un luogo sicuro".
Ogni chiave inizia con samsa_sk_, così è facile da riconoscere.
Scope (permessi)
Gli scope tengono ogni chiave limitata esattamente a ciò che le serve. Samsa offre:
Scope | Cosa permette |
|---|---|
Genera immagini | Creare nuove immagini e controllarne lo stato |
Modifica immagini | Modificare immagini esistenti e controllare lo stato delle modifiche |
Genera video | Creare nuovi video e controllarne lo stato |
Leggi modelli | Elencare e visualizzare i modelli della tua organizzazione |
Gestisci modelli | Creare, aggiornare ed eliminare modelli |
Leggi utilizzo | Leggere il saldo crediti e i dati di utilizzo |
Una chiave ha bisogno di almeno uno scope. Dai a ogni chiave il minor numero di scope necessari per il suo compito — una chiave che genera solo immagini non ha bisogno dell'accesso alla gestione dei modelli.
Tenere d'occhio l'utilizzo di una chiave
La tabella delle chiavi API mostra per ogni chiave lo stato (Attiva, Scaduta o Revocata), chi l'ha creata, quando scade, quando è stata usata l'ultima volta, quante richieste ha fatto e i crediti utilizzati (questo periodo, ultimi 30 giorni o da sempre). Apri una chiave per vedere una suddivisione dei crediti per tipo di azione. Attiva Mostra chiavi revocate per includere quelle vecchie.
Modificare e revocare
Modifica chiave ti permette di rinominare una chiave o di modificarne scope e scadenza.
Revoca chiave la disattiva. Le integrazioni che usano quella chiave smettono di funzionare immediatamente, e la revoca non può essere annullata — quindi revoca una chiave non appena non serve più o se potrebbe essere stata esposta.
Tenere le chiavi al sicuro
Tratta una chiave come una password. Non incollarla mai in codice pubblico, screenshot o chat condivise.
Conservala in un secrets manager, non in file semplici.
Usa il minor numero di scope e una data di scadenza invece di "Mai" quando puoi.
Revoca le chiavi inutilizzate e ruota le chiavi periodicamente — creane una nuova, sposta il tuo strumento su di essa, poi revoca la vecchia.
Se una chiave viene mai esposta, revocala subito e creane una sostitutiva.
Ti servono i dettagli tecnici per usare una chiave nelle richieste? Vedi la guida all'autenticazione nella documentazione per sviluppatori (si apre in una nuova scheda).