Vai al contenuto principale
Hai un guardrail salvato e vuoi che una chiave API specifica sia filtrata da esso — non l’intero workspace. È a questo che serve il binding del guardrail per chiave API: imposta guardrail_id sulla chiave e ogni chiamata /v1/* fatta con quella chiave viene filtrata alla richiesta successiva, senza redeploy e senza modifiche all’SDK. Questa pagina copre solo il binding — come collegare, come la risoluzione sceglie la policy effettiva e cosa fa l’interruttore di spegnimento. Per i tipi di regola, le azioni e gli stage, vedi il riferimento Guardrails.

​
1. Lega un guardrail per chiave API con guardrail_id

Un guardrail ha scope a livello di workspace, ma l’applicazione è decisa per chiave. Ogni chiave API porta un campo guardrail_id. Puntalo a un guardrail e quella chiave — e solo quella chiave — viene filtrata da quella policy. Questo permette a un workspace di eseguire policy diverse su chiavi diverse:
  • una chiave di produzione legata a un rigido pii-blocker,
  • una chiave di staging legata a una policy più leggera flag-only,
  • una chiave interna senza nulla collegato.
Il binding vive sulla chiave nel gateway, quindi modificare il guardrail sposta la chiave legata alla sua richiesta successiva. La tua applicazione continua a chiamare https://api.orcarouter.ai/v1/chat/completions esattamente come prima.
La chiave di relay (sk-orca-…) è ciò che la tua app invia. Collegare un guardrail ad essa è un’azione di console / token-API autenticata dalla tua sessione — non configuri mai un guardrail con la chiave di relay stessa.

​
2. Collegala nella console

Configura il binding dalla console (role-gated: modificare chiavi e guardrails richiede Developer+).
1

Apri la chiave

Vai su /console/token e crea o modifica la chiave API che vuoi filtrare.
2

Scegli il guardrail

Nell’editor della chiave, scegli il tuo guardrail dal menu a tendina Guardrail. Questo imposta guardrail_id sulla chiave.
3

Salva

Il binding ha effetto alla prossima richiesta di quella chiave. Nessun redeploy.
Dopo di che, una normale chiamata di relay con la chiave legata viene filtrata automaticamente: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Reply to jane@acme.com please"}
    ]
  }'
Se il guardrail legato maschera l’email nello stage di input, il modello upstream vede [EMAIL] e mai l’indirizzo — stessa chiamata, nessuna modifica al client.
Per filtrare ogni chiave nel workspace invece di una, imposta il guardrail come default del workspace anziché legare ogni chiave. Vedi Guardrail di default di account.

​
3. Come la risoluzione sceglie il guardrail effettivo

Su ogni richiesta, il gateway risolve esattamente un guardrail effettivo (o nessuno) in quest’ordine:
Se il guardrail_id della chiave punta a un guardrail e quel guardrail esiste ed è abilitato, si applica. Un collegamento esplicito è autoritativo — non fa mai fallback silenzioso al default del workspace.
Se la chiave non ha collegamento (guardrail_id è 0 / non impostato), si applica il guardrail di default abilitato del workspace, se ne è impostato uno.
Nessuna applicazione. La richiesta è byte-identica a un workspace che non ha mai abilitato la feature — nulla bloccato, mascherato o loggato.
La decisione è un singolo lookup indicizzato sull’hot path ed è fail-open: se la risoluzione incontra un errore transitorio, il gateway degrada a nessuna applicazione anziché far fallire la richiesta. La sicurezza degrada; la disponibilità è preservata.

​
4. L’interruttore di spegnimento: disabilita un collegamento, nessun fallback

Questa è la parte che le persone mancano. Un collegamento esplicito della chiave è una propria autorità — quindi disabilitare il guardrail collegato spegne l’applicazione per quella chiave, e non fa fallback al default del workspace.
Stato della chiaveCosa filtra la richiesta
guardrail_id → guardrail abilitatoquel guardrail
guardrail_id → guardrail disabilitatonulla (nessun fallback)
guardrail_id → eliminato / mancantenulla (nessun fallback)
guardrail_id = 0 / non impostatodefault del workspace, se presente
Disabilitare un guardrail collegato è l’interruttore di spegnimento per quella chiave, non un downgrade al default. Se vuoi che una chiave faccia fallback al default del workspace, azzera il suo collegamento (imposta guardrail_id a 0) — non limitarti a disabilitare il guardrail a cui punta.
Questa è una differenza deliberata dal firewall: una chiave con una policy del firewall collegata e disabilitata fa fallback alla policy del firewall di default del workspace, mentre un guardrail collegato e disabilitato si risolve a nessuno. Stessa idea, fallback opposto — vedi Guardrails vs. firewall.

​
5. Scollega o azzera il binding

Per smettere di filtrare una chiave con un guardrail specifico, hai due mosse distinte con esiti diversi:
  • Azzera il collegamento — imposta il guardrail_id della chiave a 0. La chiave ora si risolve al default del workspace (se esiste), o a nessuno.
  • Disabilita il guardrail — porta l’enabled del guardrail su off. Ogni chiave collegata esplicitamente ad esso ora si risolve a nessuno (per §4), mentre le chiavi che vi facevano affidamento come default del workspace scendono a nessuna applicazione.
Scegli azzera quando vuoi la chiave sul baseline del workspace; scegli disabilita quando vuoi mettere in pausa quella policy ovunque sia il collegamento nominato.

​
6. Cosa costa (e non costa) una richiesta filtrata

Una volta che un guardrail si risolve, le sue regole decidono la richiesta. I due esiti che vale la pena conoscere per una chiave legata:
  • Un block restituisce HTTP 400 con codice di errore guardrail_blocked, nominando il guardrail e la regola che ha scattato. Costa nessuna quota — un block nello stage di input scatta prima della misurazione, un block nello stage di output rimborsa la quota pre-consumata — ed è marcato skip-retry.
  • Un mask riscrive il match in un tag tipizzato (es. [EMAIL]) e lascia passare la richiesta sanitizzata; il modello upstream non vede mai l’originale.
Vedi la pagina dell’ errore guardrail_blocked per la forma esatta della risposta, e Streaming coverage per come le regole di output si comportano sulle risposte in streaming.

​
7. Dove andare dopo

Crea il tuo primo guardrail

Costruisci la policy che legherai a una chiave.

Guardrail di default di account

Filtra ogni chiave nel workspace in una volta.

Riferimento Guardrails

Tipi di regola, azioni, stage, PII, judge, grounding.

Chiavi, policy e workspace

Come i binding hanno scope nel gateway.