Chiavi API AI con ambito cliente: isola tenant, budget e abusi senza la proliferazione delle chiavi del provider

Quando un prodotto consente a molti clienti di chiamare modelli di intelligenza artificiale, spesso la chiave del fornitore a monte è la primitiva sbagliata. Una chiave del provider rappresenta in genere un account, un progetto, un'area di lavoro o un account di servizio. Il tuo prodotto ha bisogno di qualcosa di più ristretto: una chiave rivolta al cliente che identifichi un tenant, un cliente, un'applicazione, un ambiente, una policy del modello, un budget e una regola di controllo.

Questo è lo scopo delle chiavi API AI con ambito cliente. Il gateway emette la chiave, autentica le richieste, applica la policy, misura l'utilizzo e quindi chiama i fornitori upstream utilizzando credenziali nascoste. I clienti a valle non ricevono mai la chiave del provider. Ricevono un contratto stabile con la tua piattaforma.

Problema del lettore: isolamento del cliente senza un progetto fornitore per cliente

I costruttori, le agenzie e le piattaforme di rivenditori SaaS di solito devono rispondere a domande pratiche prima di poter esporre l'accesso all'IA a valle:

• Quale cliente ha generato questo utilizzo?
• Quale applicazione, ambiente o integrazione ha effettuato la chiamata?
• Quali modelli e modalità sono consentiti?
• Quanto può spendere questo cliente questo mese?
• Cosa succede se una chiave perde?
• È possibile sospendere questo cliente senza influire su tutti gli altri?
• È possibile riconciliare l'utilizzo con i report del fornitore in un secondo momento?

I progetti e gli spazi di lavoro lato provider possono aiutare, ma non sempre rappresentano l'unità giusta per ogni cliente a valle. La creazione di un limite a monte per cliente può migliorare l'isolamento e il reporting, ma crea anche un sovraccarico di provisioning, frammentazione delle quote, espansione delle credenziali e più lavoro di riconciliazione.

Una chiave emessa dal gateway fornisce al prodotto un punto di controllo a livello di cliente anche quando le credenziali upstream vengono raggruppate. Supporta inoltre modalità più efficaci, come le credenziali del fornitore vincolate al tenant o la chiave Bring Your Own Key, quando un cliente necessita di separazione contrattuale, limiti di residenza o proprietà diretta dell'account del fornitore.

Fatti, consigli e previsioni

Fatti

• I progetti OpenAI supportano membri, account di servizio, chiavi API, limiti di utilizzo, budget e risorse di progetto con ambito. Ciò rende i progetti utili come confini a monte, ma non automaticamente la giusta primitiva per ogni cliente finale.
• I report sull'utilizzo di OpenAI possono raggruppare l'utilizzo in base a dimensioni quali progetto, utente, chiave API, modello, batch e livello di servizio. Per il chargeback SaaS è ancora necessario che i record del fornitore siano uniti agli identificatori del cliente di proprietà del prodotto.
• Gli spazi di lavoro antropici separano le risorse API per caso d'uso, team, dipartimento, progetto o prodotto. Le chiavi API sono legate all'area di lavoro in cui vengono create e non possono essere spostate tra aree di lavoro.
• Il reporting sull'utilizzo e sui costi di Anthropic supporta il raggruppamento per chiave API, area di lavoro, modello, livello di servizio, finestra di contesto, residenza dei dati e opzioni relative alla velocità, con costi restituiti in intervalli giornalieri di USD.
• La guida alle chiavi API di Google Gemini consiglia di limitare le chiavi e le chiavi API Gemini sono limitate all'API Generative Language per impostazione predefinita. Restrizioni dell'applicazione come gli indirizzi IP potrebbero essere disponibili a seconda della forma di distribuzione.
• Le linee guida OWASP trattano le chiavi API come controlli obbligatori per gli endpoint protetti e affermano che le chiavi dovrebbero essere revocate quando i client violano i contratti di utilizzo.
• La guida ai segreti OWASP enfatizza il privilegio minimo, la revoca quando i segreti non sono più necessari o sono compromessi e la rotazione automatizzata per ridurre gli errori di implementazione.

Consigli

• Utilizza le chiavi del cliente emesse dal gateway come handle delle policy, non solo token di autenticazione.
• Mantieni le credenziali del fornitore a monte nascoste ai clienti a valle.
• Scrivi un registro di utilizzo del gateway al momento della richiesta, prima di fare affidamento sui dashboard del fornitore.
• Utilizzare progetti o spazi di lavoro del fornitore in modo selettivo per clienti ad alto rischio, ad alto volume, regolamentati, sensibili alla residenza o contrattualmente separati.
• Costruisci la rotazione delle chiavi come un flusso di lavoro di sovrapposizione, non come un evento di interruzione immediato.

Previsioni

• Un numero maggiore di fornitori esporrà raggruppamenti di utilizzo e controlli del budget più completi, ma l'attribuzione dei clienti di proprietà del prodotto sarà comunque necessaria per la fatturazione SaaS e i report dei rivenditori.
• Le piattaforme di rivenditori e agenzie tratteranno sempre più le chiavi gateway come oggetti commerciali: legate a piani, saldi di credito, ambiti e flussi di lavoro di supporto.
• I clienti con rigorose esigenze di conformità o di approvvigionamento richiederanno BYOK o la proprietà dell'account del fornitore, mentre la maggior parte dei clienti ordinari preferirà un contratto gateway gestito.

L'oggetto chiave del gateway

Una chiave con ambito cliente dovrebbe risolversi in un oggetto di policy strutturata. Come minimo, modella la chiave come qualcosa di più di un hash e un nome.

{
  "key_id": "key_01J9...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_4812","application_id": "app_support_bot",
  "ambiente": "produzione",
  "proprietario": {
    "tipo": "account_servizio",
    "id": "svc_support_ai"
  },
  "model_profile_id": "profile_support_standard",
  "allowed_modalities": ["testo", "immagine_input"],
  "tool_policy_id": "tools_readonly_kb",
  "budget_mensile": {
    "valuta": "USD",
    "importo": "500,00"
  },
  "limiti_tariffa": {
    "richieste_per_minuto": 120,
    "input_tokens_per_minute": 250000,
    "output_tokens_per_minute": 80000
  },
  "retention_policy": "metadata_only",
  "stato": "attivo",
  "created_at": "2026-09-05T10:00:00Z",
  "last_used_at": null
}

I campi esatti varieranno, ma il principio no: ogni richiesta in arrivo risolve la chiave nella politica del tenant prima dell'invio. L'autenticazione risponde "chi sta chiamando?" La risoluzione delle policy risponde "cosa può fare questo chiamante, quanto può spendere, dove può essere instradata la richiesta e cosa deve essere registrato?"

È qui che conta anche la strategia semantica del prodotto. Una piattaforma che vende un'API AI per agenzie potrebbe richiedere dimensioni cliente e campagna. Uno strumento di sviluppo potrebbe richiedere dimensioni dello spazio di lavoro e del repository. Un rivenditore potrebbe aver bisogno di ID cliente esterni che corrispondano al suo sistema di fatturazione.

Flusso di lavoro per la creazione delle chiavi

La creazione delle chiavi dovrebbe essere sufficientemente deterministica per l'automazione e sufficientemente rigorosa per la revisione della sicurezza.

1. Crea prima il record del cliente

Non creare chiavi orfane. La chiave deve appartenere a un inquilino e al record di un cliente prima che esista. Per le piattaforme dei rivenditori, il record del cliente deve includere ID esterni dal CRM o dal sistema di fatturazione del rivenditore, metadati del piano, raggruppamento di imposte o fatture se necessario e un campo di stato che può sospendere tutte le chiavi secondarie.

2. Allega un profilo modello

Un profilo del modello associa i nomi dei modelli rivolti al cliente ai modelli e alle funzionalità del fornitore. Ad esempio, support-standard potrebbe consentire un modello di testo bilanciato, input di immagini e nessuna esecuzione di codice. research-premium potrebbe consentire modelli a contesto lungo, ricerca sul Web e massimali per richiesta più elevati.

Non forzare le applicazioni downstream a codificare gli ID modello del provider. Utilizza il profilo gateway per gestire disponibilità, fallback, prezzi e deprecazione.

3. Imposta limiti di spesa e di tariffa

Utilizza budget e limiti di tariffa insieme. Un budget mensile previene i danni alle fatture nel tempo. I limiti di velocità impediscono che abusi improvvisi, tentativi di tempesta o loop accidentali consumino l'intero budget in pochi minuti.

I controlli utili includono:

• Budget mensile del cliente.
• Soft cap giornaliero per il rilevamento delle anomalie.
• Tasso di richieste per chiave.
• Tasso di token di input e output.
• Costo massimo stimato per richiesta.
• Limiti specifici dello strumento per la ricerca ospitata, l'elaborazione di file o l'esecuzione di codice.

L'applicazione del budget dovrebbe riservare il costo stimato prima della spedizione, liquidare il costo effettivo dopo il completamento e rilasciare la riserva non utilizzata. Ciò collega la policy chiave alla fatturazione API AI invece di considerare la fatturazione come un'attività di reporting ritardata.

4. Genera e archivia correttamente il segreto

Visualizza il segreto in testo normale una volta. Memorizza solo un hash sicuro, più un breve prefisso o un'impronta digitale per la ricerca del supporto. Il prefisso aiuta i team di supporto a identificare "la chiave che termina con 8F2A" senza vedere il segreto.

Uno schema di archiviazione tipico è:

• key_id: identificatore stabile del database.
• secret_hash: hash dell'intero segreto utilizzando una password appropriata o una strategia di hashing del token.
• secret_prefix: prefisso di visualizzazione breve non sensibile.
• impronta digitale: identificatore deterministico per la ricerca di controllo.
• created_by: utente o client API partner che ha creato la chiave.
• stato: attivo, in esaurimento, revocato, in quarantena, scaduto.

Non archiviare mai le chiavi del fornitore upstream sull'oggetto chiave del cliente. Le credenziali del fornitore appartengono a un archivio credenziali separato con le proprie regole di accesso.

Applicazione del tempo di richiesta

Il gateway dovrebbe considerare ogni model call come una decisione politica seguita dall'invio di un provider. Un percorso pratico di richiesta è simile al seguente:

1. Analizza la chiave del gateway presentata.
2. Cerca l'hash e lo stato della chiave.
3. Risolvi tenant, cliente, applicazione, ambiente, proprietario e profilo del modello.
4. Verifica se l'inquilino e il cliente sono attivi.
5. Convalida l'alias del modello, la modalità, gli strumenti, la modalità di conservazione, la regione e il livello di servizio richiesti.
6. Stima del costo della richiesta e riserva del budget.
7. Controlla i limiti di frequenza e le soglie di abuso.
8. Seleziona la modalità credenziali upstream: in pool, associata al tenant o BYOK.
9. Invio al fornitore.
10. Acquisisci utilizzo, costi, riferimenti ai fornitori, errori e segnali di sicurezza.
11. Calcola la prenotazione del budget e scrivi l'evento del registro finale.

Questa sequenza mantiene il gateway responsabile del contratto con il cliente. Le dashboard dei fornitori diventano input di riconciliazione, non l'unica fonte di verità.

Campi contabili di utilizzo che aiutano effettivamente in seguito

Un registro del gateway dovrebbe conservare dettagli sufficienti per rispondere a domande di supporto, fatturazione, abuso e routing senza richiedere l'archiviazione di prompt non elaborati per impostazione predefinita.

I campi utili includono:

• request_id e trace_id.
• tenant_id, customer_id, application_id e key_id.
• Identificatore dell'utente finale, preferibilmente pseudonimo ove appropriato.
• Alias del modello richiesto dal cliente.
• Fornitore e modello upstream risolti.
• Input, output, ragionamento, memorizzazione nella cache, audio, immagini, video e utilizzo degli strumenti, ove applicabile.
• Costo preventivato, importo riservato, costo saldato, valuta e versione del catalogo prezzi.
• ID richiesta del provider, riferimento al report sull'utilizzo, progetto, area di lavoro o dimensione di raggruppamento di chiavi API, se disponibile.
• Politica di conservazione applicata.
• Codici decisionali relativi a sicurezza, abusi o politiche.
• Categoria di errore e riprovare i metadati.

Questa struttura supporta chargeback, assistenza clienti, risposta agli incidenti e un flusso di lavoro di gestione delle chiavi API in grado di rispondere a "cosa ha fatto questa chiave?" senza esporre inquilini non correlati.

Modalità credenziali: pool, vincolato al tenant e BYOK

Credenziali del provider in pool

Nella modalità predefinita, molte chiavi del cliente vengono instradate attraverso un insieme più piccolo di credenziali del fornitore. Ciò è operativamente semplice e riduce l'espansione incontrollata del lato provider. Funziona quando il gateway dispone di una forte attribuzione del tenant, applicazione del budget, limitazione della velocità, isolamento degli abusi e controlli dei limiti della cache.

Il compromesso è che i report lato fornitore possono mostrare solo la credenziale del gateway o il progetto del fornitore. È necessario unire i record del fornitore ai record contabili del gateway per produrre fatturazione e analisi a livello di cliente.

Credenziali del provider vincolato al tenant

Per tenant più grandi o più rischiosi, vincola un tenant a un progetto, un'area di lavoro, un account di servizio o una chiave del provider dedicato. Ciò garantisce una maggiore separazione a monte e può semplificare il reporting lato fornitore. Può anche fornire un limite rigido di quota se il provider supporta limiti a tale limite.

Il costo è la complessità operativa. Il provisioning, la rotazione, i limiti del fornitore, la risposta agli incidenti e la riconciliazione ora avvengono su più oggetti upstream.

Porta la tua chiave

BYOK può essere utile quando i clienti devono possedere l'account del fornitore, negoziare il proprio contratto con il fornitore o mantenere separata la fatturazione con il fornitore. Il gateway applica comunque profili di modello, policy di routing, analisi e controlli a livello di applicazione, ove possibile.

Il compromesso è la complessità del supporto. L'account del fornitore di ciascun cliente può avere modelli di accesso, quote, prezzi, impostazioni di conservazione e stato dell'incidente diversi. Il gateway deve rilevare e spiegare chiaramente queste differenze.

Revoca e quarantena

La revoca dovrebbe bloccare immediatamente le nuove richieste per una chiave del cliente senza ruotare le credenziali del fornitore upstream non correlate. Questo è uno dei principali vantaggi delle chiavi virtuali.

Utilizza stati separati per diverse azioni operative:

• attivo: le richieste sono consentite.
• drenaggio: la vecchia chiave viene accettata durante una finestra di rotazione, ma vengono emessi avvisi ed eventi di controllo.
• revocato: le nuove richieste vengono rifiutate in modo permanente.
• in quarantena: le nuove richieste vengono bloccate a causa di abuso, pagamento, policy o risposta a un incidente.
• scaduto: la chiave ha superato la sua durata e deve essere sostituita.

La quarantena dovrebbe essere reversibile una volta risolto l'incidente. La revoca di solito non dovrebbe essere reversibile, perché il ripristino di vecchi segreti aumenta la confusione e il rischio.

Quando una chiave viola le norme di utilizzo, registra il motivo, l'attore, l'ora e l'ambito di applicazione. Se la decisione è stata automatizzata, conserva la versione della regola e i segnali che l'hanno attivata. Ciò mantiene le conversazioni con i clienti basate sui fatti.

Rotazione senza interruzione della produzione

La rotazione delle chiavi dovrebbe utilizzare un flusso di lavoro di sovrapposizione a due chiavi:

1. Crea una chiave sostitutiva con lo stesso cliente, applicazione, profilo modello e limiti, a meno che l'operatore non li modifichi intenzionalmente.
2. Visualizza il nuovo segreto una volta.
3. Contrassegna la vecchia chiave come drenante.
4. Accetta entrambe le chiavi per un periodo limitato, ad esempio 7, 14 o 30 giorni a seconda del piano e del rischio del cliente.
5. Emette avvisi di utilizzo sulla chiave di scarico.
6. Informa il proprietario o il client API Partner quando la vecchia chiave è ancora utilizzata in prossimità della scadenza.
7. Revoca la vecchia chiave alla fine della finestra.
8. Mantieni l'attribuzione su entrambi gli ID chiave per lo stesso cliente e applicazione.

Ciò evita la comune modalità di errore in cui un miglioramento della sicurezza diventa un'interruzione della produzione. La rotazione è ancora un controllo, ma diventa un flusso di lavoro operativo con prove e scadenze.

Superficie API partner

Se le piattaforme downstream gestiscono i clienti in modo programmatico, esponi le operazioni chiave tramite un'API partner. L'API dovrebbe supportare chiavi di idempotenza ed eventi di controllo perché il provisioning spesso avviene all'interno dei flussi di lavoro di fatturazione, onboarding o CRM.

Endpoint minimi:

• POST /customers: crea o inserisce un cliente.
• POST /customers/{customer_id}/keys: crea una chiave.
• GET /customers/{customer_id}/keys: elenca chiavi e stati.
• PATCH /keys/{key_id}: aggiorna ambiti, proprietario, limiti, profilo del modello o stato.
• POST /keys/{key_id}/rotate: crea la sostituzione e contrassegna la vecchia chiave come drenante.
• POST /keys/{key_id}/revoke: revoca immediatamente.
• GET /customers/{customer_id}/usage: restituisce utilizzo e costo in base a intervallo di tempo, chiave, app, modello o dimensione utente finale.

Ogni richiesta mutante dovrebbe accettare una chiave di idempotenza. Ogni modifica dovrebbe scrivere un evento di controllo con attore, destinazione, campi prima e dopo, IP di origine o identità del client e motivo, ove disponibile.

Quando utilizzare progetti o spazi di lavoro del fornitore

Non considerare le chiavi del gateway e i limiti del provider come reciprocamente esclusivi. Risolvono diversi problemi.

Utilizza le chiavi gateway per il normale controllo a livello di cliente:

• Attribuzione per cliente.
• Chiavi per applicazione.
• Budget e limiti di tariffa.
• Sospensione rapida.
• Flussi di lavoro di rotazione.
• Analisi dell'utilizzo e reportistica dei rivenditori.

Aggiungi progetti di fornitori, spazi di lavoro o credenziali di fornitori dedicati quando il cliente necessita di una separazione più forte:

• Volume mensile elevato che merita quote dedicate.
• Carichi di lavoro regolamentati con requisiti espliciti di residenza o conservazione.
• Separazione contrattuale delle fatture.
• Budget lato fornitore o limiti rigidi delle quote.
• Monitoraggio dedicato degli abusi o limiti di revisione della sicurezza.
• Account fornitore di proprietà del cliente tramite BYOK.

L'impostazione predefinita pratica è l'isolamento forzato dal gateway con confini rigidi selettivi a monte. Ciò mantiene semplice il percorso comune preservando al contempo un percorso di escalation per i clienti che necessitano di una maggiore separazione.

Lista di controllo per l'implementazione

• Definisci uno schema di chiavi del cliente con tenant, cliente, applicazione, ambiente, proprietario, profilo del modello, limiti, criteri di conservazione e stato.
• Hash i segreti a riposo e visualizza il testo in chiaro solo una volta.
• Chiavi del gateway separate dall'archiviazione delle credenziali del provider upstream.
• Risolvi ogni richiesta nella policy prima dell'invio.
• Prenotare il budget prima delle chiamate del fornitore e saldarlo dopo che si conosce l'utilizzo finale.
• Registra l'utilizzo con cliente, chiave, alias modello, modello upstream, categorie di token, utilizzo dello strumento, costo preventivato, costo saldato e riferimenti al fornitore.
• Implementare gli stati attivo, in scarico, revocato, in quarantena e scaduto.
• Supporta la sovrapposizione della rotazione a due tasti.
• Esponi le operazioni API del partner con chiavi di idempotenza.
• Utilizzare progetti o spazi di lavoro del fornitore solo laddove il loro costo operativo è giustificato.

Conclusione attuabile

L'isolamento del cliente per l'accesso all'intelligenza artificiale dovrebbe in genere iniziare dalla chiave del gateway, non dalla chiave del provider. La chiave del gateway è il contratto rivolto al cliente: nomina il tenant, il cliente, l'applicazione, il profilo del modello, il budget, il limite di tariffa, la regola di conservazione e la politica di controllo. La chiave del fornitore è un dettaglio di implementazione dietro quel contratto.

Questa architettura offre agli sviluppatori SaaS e alle piattaforme di rivenditori revoca rapida, attribuzione accurata, budget per cliente, rotazione controllata e analisi utili sull'utilizzo senza creare per impostazione predefinita un progetto di fornitore a monte per ogni cliente. Utilizza progetti upstream, aree di lavoro, credenziali legate al tenant o BYOK quando il rischio, il volume, la residenza o il contratto lo richiedono. Per il percorso ordinario, applica l'isolamento del cliente nel registro del gateway e nel motore delle policy, quindi riconcilia i record del fornitore in seguito.

Leggi correlati

• Provisioning dell'API partner idempotente per clienti, chiavi e crediti