Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Autenticazione, chiavi API e organizzazione

Lezione 3 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Autenticazione, chiavi API e organizzazione
  2. Crea il tuo account e ottieni una chiave
  3. Quale tipo di chiave scegliere
  4. Organizzazioni e progetti
  5. Non esporre mai le tue chiavi
  6. Verifica la tua configurazione
  7. Punti chiave

Autenticazione, chiavi API e organizzazione

Prima di scrivere una singola riga di codice, devi configurare il tuo accesso alle API. Questa lezione spiega come creare le chiavi, strutturare l’accesso tramite organizzazioni e progetti e adottare le precauzioni di sicurezza necessarie per evitare il classico incubo: pubblicare per sbaglio una chiave in un repository pubblico, dove uno sconosciuto potrebbe sfruttarla durante la notte.

Crea il tuo account e ottieni una chiave

La procedura si articola in tre passaggi. Per prima cosa, vai su platform.openai.com e crea un account; riceverai automaticamente dei crediti gratuiti per iniziare a sperimentare. Successivamente, naviga nella sezione API Keys della dashboard e genera una nuova chiave. Vedrai questa chiave una sola volta: copiala immediatamente, ma non incollarla nel tuo codice.

# La tua chiave API ha questo aspetto (non condividerla mai!)
# sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Best practice: usa una variabile d'ambiente
import os
api_key = os.environ.get("OPENAI_API_KEY")

Il terzo passaggio consiste nel dichiarare la variabile d’ambiente, operazione che dipende dalla tua piattaforma. Su una macchina di sviluppo, un file .env caricato tramite python-dotenv è spesso la soluzione più comoda. Su un server, preferisci una variabile d’ambiente definita dal tuo orchestratore o dal servizio di gestione dei segreti.

# Linux / macOS — aggiungi a ~/.bashrc o ~/.zshrc
export OPENAI_API_KEY="sk-proj-your-key-here"

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-proj-your-key-here"

# File .env (con python-dotenv)
# .env
OPENAI_API_KEY=sk-proj-your-key-here

Quale tipo di chiave scegliere

Le chiavi di progetto, identificabili dal prefisso sk-proj-, sono legate a un progetto specifico e offrono il miglior controllo. Le userai quasi sempre. L’SDK le rileva automaticamente una volta impostata la variabile d’ambiente; ecco perché OpenAI() viene istanziato senza argomenti in tutti gli esempi di questo corso.

from openai import OpenAI

# L'SDK rileva automaticamente OPENAI_API_KEY
client = OpenAI()

# Oppure specificala esplicitamente (sconsigliato in produzione)
client = OpenAI(api_key="sk-proj-...")

Le chiavi di servizio costituiscono il secondo tipo. Progettate per applicazioni server che richiedono privilegi elevati, concedono permessi aggiuntivi e richiedono quindi maggiore cautela: conservale in un vault per segreti e non distribuirne mai il valore su una workstation di sviluppo.

Organizzazioni e progetti

L’accesso è strutturato su tre livelli annidati:

  1. Organizzazione: la tua azienda o il tuo team
  2. Progetto: un raggruppamento logico (ad esempio “Chatbot di Produzione”, “Analisi Dati”)
  3. Chiave API: collegata a un progetto specifico

Se appartieni a più organizzazioni, specifica quella che intendi utilizzare quando istanzi il client:

from openai import OpenAI

# Specifica l'organizzazione (utile se appartieni a più organizzazioni)
client = OpenAI(
    organization="org-xxxxxxxxxxxx",
    project="proj-xxxxxxxxxxxx"
)

Prenditi il tempo necessario per suddividere il tuo utilizzo in progetti invece di instradare tutto attraverso un’unica chiave. Ne vedrai i benefici al primo segnale di problema. Ogni progetto dispone del proprio tracciamento dell’utilizzo, permettendoti di attribuire i costi a una funzionalità specifica anziché a un totale mensile opaco. Anche i limiti di frequenza (rate limits) sono separati: un job batch notturno che satura la propria quota non impedirà al tuo chatbot di rispondere ai clienti. Puoi quindi assegnare membri diversi a ciascun progetto e, cosa cruciale, revocare una chiave compromessa senza interrompere le altre applicazioni.

Non esporre mai le tue chiavi

La regola è semplice e assoluta: una chiave non deve mai apparire nel codice sorgente. Il contrasto tra i due frammenti seguenti vale più di un lungo discorso.

# SBAGLIATO — chiave hardcoded nel codice
client = OpenAI(api_key="sk-proj-abc123")  # PERICOLO!

# CORRETTO — variabile d'ambiente
client = OpenAI()  # Legge automaticamente OPENAI_API_KEY

# CORRETTO — file .env con python-dotenv
from dotenv import load_dotenv
load_dotenv()
client = OpenAI()

La conseguenza logica riguarda il tuo .gitignore, che deve escludere i file di configurazione locali prima del tuo primo commit, non dopo. Una chiave pubblicata e poi cancellata rimane comunque presente nella cronologia del repository.

# AGGIUNGI SEMPRE queste righe al tuo .gitignore
.env
.env.local
.env.production
*.key

Infine, pianifica una rotazione regolare, ogni 90 giorni. Puoi farlo senza tempi di inattività: crea una nuova chiave, aggiorna i tuoi deployment ed elimina quella vecchia solo quando nulla la utilizza più.

Verifica la tua configurazione

Prima di procedere, esegui questo script. Controlla la presenza della chiave, ne visualizza una versione troncata per confermare che sia quella corretta ed effettua quindi una chiamata reale. Riesegui questo test ogni volta che un ambiente si comporta in modo strano.

from openai import OpenAI
import os

def verify_configuration():
    """Verifica che la configurazione API sia corretta."""
    
    # Controlla la presenza della chiave
    api_key = os.environ.get("OPENAI_API_KEY")
    if not api_key:
        print("ERRORE: OPENAI_API_KEY non definita")
        return False
    
    print(f"Chiave rilevata: {api_key[:8]}...{api_key[-4:]}")
    
    # Testa la connessione
    try:
        client = OpenAI()
        response = client.responses.create(
            model="gpt-5.6-terra",
            input="Reply only: OK"
        )
        print(f"Connessione riuscita: {response.output_text}")
        return True
    except Exception as e:
        print(f"ERRORE di connessione: {e}")
        return False

verify_configuration()
# Risultato atteso:
# Chiave rilevata: sk-proj-...xxxx
# Connessione riuscita: OK

Punti chiave

  • Usa chiavi di progetto (sk-proj-...) per ogni applicazione
  • Conserva le tue chiavi nelle variabili d’ambiente, mai nel codice
  • Organizza il tuo accesso con la gerarchia Organizzazione → Progetto → Chiave
  • Esegui una rotazione regolare delle tue chiavi (ogni 90 giorni)
  • Aggiungi sempre .env al tuo .gitignore