Vai al contenuto principale
Stai costruendo un SaaS dove molti clienti-tenant condividono una sola codebase e un solo workspace OrcaRouter. Ogni tenant invia prompt ed esegue agent attraverso il tuo gateway, e il problema difficile è il blast-radius: una chiave di tenant trapelata, un agent di tenant fuori controllo, o le PII di un tenant che finiscono nei log di un altro non possono essere lasciate sconfinare oltre il confine. Questa ricetta collega i tre controlli che rendono tenant-safe un gateway condiviso — una chiave con scope per tenant, una policy a livello di workspace che ogni tenant eredita, e override per-tenant dove un tenant ha bisogno di più — tutto dalla console, con zero modifiche al codice della tua applicazione.
Tutto qui si collega al tuo workspace ed è configurato dalla console. La tua app continua a chiamare https://api.orcarouter.ai/v1/chat/completions con la chiave sk-orca-... di ciascun tenant — cambia solo la policy nel gateway. Le azioni di config richiedono i ruoli indicati per ciascun passaggio; solo le chiamate di relay /v1/* usano una chiave di tenant.

​
1. Il modello di sicurezza AI multi-tenant

Un gateway multi-tenant ha una forma di threat diversa da una singola app. I rischi che contano scalano con il numero di tenant:

Leak della chiave = blast radius di un tenant

Una chiave di tenant trapelata non dovrebbe poter drenare il tuo account, chiamare modelli che non hai mai esposto, o andare oltre il budget di quel tenant.

Sanguinamento di dati cross-tenant

Le PII di un tenant che finiscono in log condivisi, o in una risposta instradata a un altro tenant, rompono la tua promessa di isolamento dei dati.

Un agent di tenant rumoroso

L’agent di un tenant in loop su un tool o che recupera host arbitrari non dovrebbe degradare il gateway per tutti gli altri.

Compliance per-tenant

Un tenant regolamentato può aver bisogno di masking delle PII e data-residency che il resto dei tuoi tenant no.
Il modello qui sotto è a due layer: una baseline di workspace che ogni chiave di tenant eredita, più scope e override per-chiave che irrigidiscono un tenant senza toccare gli altri. Vedi scope di chiavi, policy, workspace per le regole di risoluzione complete.

​
2. La baseline: una policy di workspace che ogni tenant eredita

Scrivi la tua postura di sicurezza una volta a livello di workspace così ogni chiave di tenant la eredita per default — nessuna duplicazione per-tenant.
1

Un guardrail di default

In Guardrails → New guardrail, scrivi una policy nominata (es. tenant-baseline) e marcala come default del workspace (is_default). Aggiungi una regola PII, stage input, azione mask, così la richiesta di nessun tenant porta PII grezze a monte:
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "credit_card", "ssn", "ip"],
  "entity_actions": { "credit_card": "block", "ssn": "block" }
}
Qualsiasi chiave di tenant senza collegamento esplicito di guardrail ricade su questo default. Scrivere un guardrail richiede il ruolo Developer.
2

Una policy del firewall di default

Se i tuoi tenant eseguono agent, fai lo stesso sul piano delle azioni: in Firewall → Policies, scrivi una policy di default o — più veloce — apri Firewall → Posture e applica il livello di autonomia balanced. Quello auditerà le chiamate a tool di ogni tenant e segnala le PII a livello di workspace mentre nega le azioni più distruttive, così osservi il comportamento reale dei tenant prima di applicare ampiamente. Ruolo Developer.
Fai il rollout della baseline in ordine observe → shadow → enforce così una nuova regola non può rompere un tenant a metà volo. Una policy del firewall supporta un flag shadow_mode per-policy (i verdetti applicativi loggano come [shadow] would …); avvia le regole dei guardrail con l’azione flag. Vedi modalità di applicazione.

​
3. Una chiave con scope per tenant

Questo è il cuore dell’isolamento dei tenant: non condividere mai una chiave tra tenant, e non consegnare mai a un tenant la tua chiave a livello di account. Conia una chiave per tenant, con scope esattamente a ciò che quel tenant può fare. In API Keys → New key, imposta:
Imposta credit_limit_usd al tetto di quel tenant (0 = illimitato). Questo è il controllo multi-tenant singolo più importante: una chiave di tenant trapelata o abusata può solo mai bruciare il budget di quel tenant, mai il tuo account. Vedi denial-of-wallet.
Attiva model_limits (model_limits_enabled) ed elenca solo il/i modello/i che il piano di quel tenant include — così una chiave trapelata non può eseguire un modello costoso che il tenant non ha mai pagato.
Imposta environment (un’etichetta di deployment in forma libera, es. prod / staging) così il traffico di un tenant è attribuibile nei tuoi log e puoi distinguere a colpo d’occhio le chiavi di produzione da quelle di test.
Imposta allow_ips sugli IP di egress del backend di quel tenant se chiama da un server fisso, e expired_time per i tenant in trial o a tempo (-1 = non scade mai).
Ogni chiave di tenant eredita automaticamente il guardrail tenant-baseline del workspace e la policy del firewall di default — hai coniato una chiave con scope, ed è già governata. La chiave è mascherata in visualizzazione dopo la creazione, quindi copiala una sola volta quando fai il provisioning del tenant.

​
4. Override per-tenant — irrigidisci uno senza toccare il resto

La maggior parte dei tenant cavalca la baseline. Quando uno ha bisogno di più — un tenant regolamentato, un tier enterprise, un tenant su una lista di probation — collega una policy nominata più stretta a quella chiave soltanto:
Impostato sulla chiaveEffetto per quel solo tenant
guardrail_idSostituisce un guardrail nominato più stretto (es. block-on-PII).
firewall_policy_idSostituisce una policy del firewall più stretta (es. tool default-deny).
La risoluzione differisce tra i due piani — conosci la differenza:
Un guardrail_id esplicito (quando esiste ed è abilitato) si applica sempre e non ricade mai silenziosamente. Se quel guardrail collegato è disabilitato, la chiave non riceve alcun guardrail — non scende al default del workspace. Lascia guardrail_id non impostato (0/null) per ereditare il default tenant-baseline.
Un firewall_policy_id collegato si applica quando esiste ed è abilitato; se quella policy è disabilitata, la chiave ricade sulla policy del firewall di default del workspace. (Questo è l’opposto del comportamento di interruttore del guardrail — per design.)
Modificare una policy nominata sposta ogni chiave ad essa collegata alla chiamata successiva. Se più tenant condividono una policy più stretta, una modifica li colpisce tutti in una volta. Usa una policy nominata distinta per classe di isolamento, non una sola policy condivisa gigante, quando i tenant hanno bisogno di regole genuinamente diverse.

​
5. Un esempio concreto a due tier

Diciamo che gestisci un tier gratuito e un tier enterprise regolamentato su un solo workspace:
  1. Baseline di workspace — guardrail tenant-baseline (mask PII su input, block su carta/SSN) come is_default, più il livello di autonomia balanced del firewall. Ogni tenant eredita questo.
  2. Chiave di tenant free-tier — nessun guardrail_id (eredita la baseline), model_limits fissato su openai/gpt-4o-mini, un credit_limit_usd basso.
  3. Chiave di tenant enterprise — guardrail_id impostato su un guardrail enterprise-pii più stretto (PII block, non mask, su input; block dei secrets allo stage output), un firewall_policy_id con una allow-list di tool più stretta, un cap di credito più alto, e allow_ips fissato sul loro backend.
Entrambi i tier chiamano lo stesso endpoint /v1/chat/completions con la propria chiave. Il gateway risolve la policy giusta per chiave — il codice della tua applicazione è identico per ogni tenant.

​
6. Compliance e residency per-tenant

Un tenant regolamentato spesso ha bisogno di un’attestazione che il resto no. La Compliance gira come un pari di workspace di guardrail e firewall:
  • Sfogliare il catalogo dei framework e la readiness è aperto a qualsiasi Member ed è gratuito — conferma la copertura per il framework che un tenant chiede (soc2, hipaa, gdpr, iso_27001, pci_dss e altri).
  • Installare un pack (POST /api/compliance/packs/:key/install) materializza i guardrail e le policy del firewall corrispondenti nel tuo workspace; richiede Admin del workspace e un piano a pagamento.
  • La Data residency fissa la regione del tuo artefatto di report di compliance (us / eu / uk / ap / cn / global) tramite PUT /api/compliance/residency (Admin). Le letture cross-region sono negate.
La residency qui governa l’artefatto del report di compliance, non il geo-pinning dei dati di inferenza. Per la storia dei request-log: i log si conservano per un default di 30 giorni (cap rigido a 180), e un’auto-cancellazione dell’utente esegue una grace di 30 giorni poi una purga delle PII che cascata ai guardrail match e ai request-log di quell’utente.
Per un’esecuzione completa di evidenza sottoposta ad audit, vedi generare evidenza SOC 2 e deploy per HIPAA.

​
7. Osserva ogni tenant da un solo workspace

Tutta l’osservabilità ha scope a livello di workspace, così un solo insieme di feed copre tutti i tuoi tenant — filtrabile fino a uno solo:
  • Guardrails → Matches (qualsiasi Member) — ogni regola che è scattata su tutti i tenant: tipo, azione, stage, dettaglio. La sottostringa corrispondente è registrata solo se Log raw content è attivo per quel guardrail (disattivato per default — la postura conservativa sulla privacy, che conta di più in multi-tenant). Marca un falso positivo per mettere a punto (Admin).
  • Firewall → Events / Runs (Developer+) — ogni chiamata a tool, aggregata per esecuzione dell’agent, così il loop di un tenant rumoroso o un egress nuovo spicca.
  • Feed delle anomalie (Member) — picchi di rate/costo valutati rispetto a una baseline ora-della-settimana appresa colgono un tenant che brucia fuori pattern anche quando ogni chiamata è individualmente consentita.
Una richiesta bloccata restituisce HTTP 400 (guardrail_blocked / firewall_blocked), non costa quota a quel tenant, ed è marcata skip-retry — il confine ha tenuto senza addebitare al tenant il rifiuto.

​
8. Dove approfondire

Scope di chiavi, policy, workspace

L’ordine di risoluzione completo per il collegamento della chiave e i default del workspace.

Riferimento Guardrails

Ogni tipo di regola, entità PII e override per-entità per intero.

Riferimento Firewall

Verdetti, superfici, livelli di autonomia e il piano della policy.

Fermare l'esfiltrazione di dati

Blinda l’egress in uscita di un agent di tenant.