Vai al contenuto principale
Quando un auditor chiede “dimostra che il tuo traffico AI è governato”, non vuoi fare screenshot di una console. OrcaRouter trasforma la tua postura live di guardrail e firewall in un report di evidenza firmato e verificabile pubblicamente mappato a un framework normativo — SOC 2, HIPAA, GDPR, l’EU AI Act e altri. Questa pagina è la superficie API per quel workflow: come sfogliare il catalogo, installare un pack, generare un report e lasciare che un auditor verifichi la firma senza un account OrcaRouter. La compliance è il terzo piano nel control stack di OrcaRouter, accanto a Guardrails (testo) e Firewall (chiamate a tool). Un compliance pack è semplicemente un bundle pre-creato di quei due — installarne uno materializza una vera policy di guardrail e firewall, modificabile, nel tuo workspace.
Tutte le rotte /api/compliance/* si autenticano con il tuo session / access token di console (lo stesso login che usi per la dashboard), non con una chiave di relay sk-orca-…. Configura tutto dalla console; la superficie REST qui sotto serve ad automatizzare la raccolta di evidenza in CI.

​
1. Cosa copre il riferimento API compliance

Due gruppi di rotte, due pubblici:
GruppoAuthPubblico
/api/compliance/*Sessione di consoleTu + i tuoi auditor (nel workspace)
/api/public/compliance/*Nessuna (token / firma)Chiunque verifichi un report
Le letture nel primo gruppo — sfogliare il catalogo, i pack installati, la readiness, la residency e i metadati dei report — sono aperte a ogni membro del workspace e gratuite. Ogni scrittura (installare un pack, andare live, generare o scaricare report, cambiare residency, condividere) richiede Admin del workspace (enforced lato server). Un piano a pagamento è inoltre richiesto per installare un pack, portarlo live ed esportare CSV/JSON o generare più del singolo report gratuito — ma non per cambiare la residency o generare il tuo primo PDF.

​
2. Sfoglia il catalogo e controlla la readiness

Parti in sola lettura. Questi tre endpoint non richiedono ruoli speciali e non costano nulla:
Restituisce il registro dei framework. OrcaRouter fornisce pack per i principali regimi di sicurezza, privacy e AI-governance — inclusi soc2, hipaa, gdpr, uk_gdpr, eu_ai_act, iso_27001, iso_42001, nist_ai_rmf, nist_800_53, pci_dss, glba, ccpa, e una lunga coda di leggi regionali sulla privacy (PIPL, APPI, PIPA, LGPD, PIPEDA, DPDP e gli atti dei singoli stati USA). OWASP Top 10 for LLM Applications (owasp_llm) viene fornito come pack di prima classe anch’esso — materializza veri controlli di guardrail e firewall (prompt injection, output insicuro, divulgazione sensibile, eccessiva agency) proprio come ogni altro framework.
Elenca i pack già materializzati in questo workspace, ciascuno con la sua modalità di ciclo di vita (observe o enforce) e la policy di guardrail + firewall che ha creato.
Valuta la tua postura attuale rispetto alla checklist di ciascun framework: quali controlli i tuoi guardrails e le tue regole del firewall live soddisfano già, e quali sono ancora gap organizzativi che devi colmare da solo. Leggilo prima di installare qualsiasi cosa.

​
3. Installa un pack

Installare un pack è il momento di valore: scrive un vero Guardrail (piano testo/dati) e una WorkspaceFirewallPolicy con le sue regole (piano chiamate a tool) nel tuo workspace, etichettati al framework. Entrambi sono completamente modificabili dopo — il pack è un punto di partenza, non un template bloccato. 
# Admin + piano a pagamento. Installa prima in observe mode.
curl -X POST https://api.orcarouter.ai/api/compliance/packs/soc2/install \
  -H "Authorization: Bearer $ORCA_CONSOLE_TOKEN"
I nuovi pack arrivano in observe mode — azioni dei guardrail forzate a flag, firewall in shadow/solo-log — così puoi osservare la copertura prima che qualsiasi cosa blocchi il traffico live. Quando sei pronto, promuovilo: 
curl -X POST https://api.orcarouter.ai/api/compliance/packs/soc2/golive \
  -H "Authorization: Bearer $ORCA_CONSOLE_TOKEN"
golive porta la policy di guardrail e firewall materializzata in applicazione. Eseguilo dopo aver rivisto le modalità di applicazione così sai esattamente cosa deny e mask faranno al traffico live.
Altre scritture sui pack (tutte Admin): POST …/packs/:key/controls per collegare un singolo controllo, POST …/packs/:key/update per ri-sincronizzare dopo che il catalogo cambia, e DELETE …/packs/:key per disinstallare.

​
4. Genera un report di evidenza firmato

Il report è l’artefatto che consegni a un auditor. Ognuno è renderizzato dalla tua postura live, sottoposto a content-hash con SHA-256 e firmato con Ed25519 così non può essere modificato silenziosamente dopo i fatti. 
curl -X POST https://api.orcarouter.ai/api/compliance/reports \
  -H "Authorization: Bearer $ORCA_CONSOLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"framework":"soc2","format":"pdf"}'
I formati sono pdf, json e csv.
Il tuo primo report PDF è gratuito così puoi fare la demo dell’artefatto. L’export CSV/JSON e i report aggiuntivi fanno parte del piano a pagamento — il report è l’evidenza vendibile, quindi il gateway restituisce un messaggio amichevole di upgrade anziché un errore secco quando raggiungi il tetto gratuito.
Elenca e recupera i report con GET …/reports e GET …/reports/:id; scarica il file renderizzato con GET …/reports/:id/download (Admin).

​
5. Lascia che un auditor lo verifichi — nessun account richiesto

Tre endpoint pubblici rendono un report controllabile in modo indipendente da chiunque possieda il file:

Ottieni la chiave pubblica

GET /api/public/compliance/pubkey restituisce la chiave pubblica Ed25519 con cui sono firmati i tuoi report.

Verifica una firma

POST /api/public/compliance/verify controlla la firma e l’hash di contenuto di un report e dice al chiamante se è stato manomesso.

Condividi con un auditor

Conia un link in sola lettura da POST …/reports/:id/share (Admin); l’auditor apre GET /api/public/compliance/share/:token — nessun login.
Poiché la verifica è pubblica e controllabile offline, un auditor non tocca mai il tuo workspace o il tuo traffico — conferma la crittografia e legge l’evidenza.

​
6. Data residency

La residency qui è la regione sotto cui la tua evidenza di compliance è stampata e memorizzata — us, eu, uk, ap, cn o global. Governa dove vivono i report e da quale regione possono essere serviti; un report viene trattenuto se letto da una regione non corrispondente. (Questo è un controllo sull’artefatto-evidenza, non il geo-pinning del tuo traffico di inferenza.) 
curl -X PUT https://api.orcarouter.ai/api/compliance/residency \
  -H "Authorization: Bearer $ORCA_CONSOLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"region":"eu"}'
Leggi l’impostazione corrente con GET …/residency (qualsiasi membro); cambiarla è Admin.

​
7. Retention, erasure e audit

Il piano compliance è supportato dalle stesse garanzie di ciclo di vita dei dati che si applicano in tutto il gateway:
I log delle richieste sono conservati 30 giorni di default e 180 giorni massimo — il gateway clamppa qualsiasi cosa più lunga. La retention alimenta direttamente il tuo punteggio di readiness.
Una richiesta di cancellazione dell’account apre un periodo di grazia di 30 giorni (il default), dopo il quale i PII dell’account vengono irreversibilmente cancellati: la cascata redige gli identificatori sui log delle richieste conservati ed elimina i match dei guardrail, gli eventi del firewall e i record di agent-trace con scope utente.
La sezione change-log di un report di compliance è tratta dall’audit log del workspace, con scope sul periodo del report. Le email dei membri e degli admin sono mascherate di default nel report esportato (es. j•••@acme.com) a meno che i PII completi non siano esplicitamente richiesti al momento della generazione. Vedi il catalogo delle azioni di audit.

​
Dove andare dopo

API Guardrail

La policy del piano testo/dati che un compliance pack materializza.

API Firewall

Il piano della policy chiamate a tool che il pack scrive accanto ad esso.

Control stack

Come guardrail, firewall e compliance si compongono in un’unica postura.

Codici di errore

Ogni stato che il gateway può restituire, inclusi paywall e gate di ruolo.
Per le definizioni dei termini — compliance pack, report firmato, data residency, diritto all’oblio — vedi il glossario dei concetti.