Saltar para o conteúdo principal
Você tem um guardrail salvo e quer que uma chave de API específica seja filtrada por ele — não o workspace inteiro. É para isso que serve o vínculo de guardrail por chave de API: defina guardrail_id na chave e cada chamada /v1/* feita com essa chave é filtrada já na próxima requisição, sem redeploy e sem mudança de SDK. Esta página cobre apenas o vínculo — como vincular, como a resolução escolhe a política efetiva e o que o botão de desligar faz. Para os tipos de regra, ações e estágios, veja a referência de Guardrails.

​
1. Vincule um guardrail por chave de API com guardrail_id

Um guardrail tem escopo de workspace, mas o enforcement é decidido por chave. Cada chave de API carrega um campo guardrail_id. Aponte-o para um guardrail e essa chave — e somente essa chave — é filtrada por essa política. Isso permite que um workspace rode políticas diferentes em chaves diferentes:
  • uma chave de produção vinculada a um pii-blocker estrito,
  • uma chave de staging vinculada a uma política flag-only mais leve,
  • uma chave interna sem nada vinculado.
O vínculo vive na chave dentro do gateway, então editar o guardrail desloca a chave vinculada já na próxima requisição. Sua aplicação continua chamando https://api.orcarouter.ai/v1/chat/completions exatamente como antes.
A chave de relay (sk-orca-…) é o que sua app envia. Vincular um guardrail a ela é uma ação de console / API de token autenticada pela sua sessão — você nunca configura um guardrail com a própria chave de relay.

​
2. Vincule no console

Configure o vínculo a partir do console (role-gated: editar chaves e guardrails exige Developer+).
1

Abra a chave

Vá em /console/token e crie ou edite a chave de API que você quer filtrar.
2

Escolha o guardrail

No editor de chave, escolha seu guardrail no menu Guardrail. Isso define guardrail_id na chave.
3

Salve

O vínculo entra em vigor na próxima requisição dessa chave. Sem redeploy.
Depois disso, uma chamada de relay normal com a chave vinculada é filtrada 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 o guardrail vinculado mascara email no estágio de input, o modelo upstream vê [EMAIL] e nunca o endereço — mesma chamada, nenhuma mudança no cliente.
Para filtrar cada chave do workspace em vez de uma, defina o guardrail como o padrão do workspace em vez de vincular cada chave. Veja Guardrail padrão de conta.

​
3. Como a resolução escolhe o guardrail efetivo

Em cada requisição, o gateway resolve exatamente um guardrail efetivo (ou nenhum) nesta ordem:
Se o guardrail_id da chave aponta para um guardrail e esse guardrail existe e está habilitado, ele se aplica. Um vínculo explícito é autoritativo — ele nunca cai silenciosamente para o padrão do workspace.
Se a chave não tem vínculo (guardrail_id é 0 / não definido), o guardrail padrão habilitado do workspace se aplica, se houver um definido.
Sem enforcement. A requisição é byte-idêntica à de um workspace que nunca habilitou o recurso — nada bloqueado, mascarado ou registrado.
A decisão é uma busca indexada no caminho quente e é fail-open: se a resolução encontrar um erro transitório, o gateway degrada para sem enforcement em vez de falhar a requisição. A segurança degrada; a disponibilidade é preservada.

​
4. O botão de desligar: desabilite um vínculo, sem fallback

Esta é a parte que as pessoas perdem. Um vínculo explícito de chave é sua própria autoridade — então desabilitar o guardrail vinculado desliga o enforcement para essa chave, e ele não cai para o padrão do workspace.
Estado da chaveO que filtra a requisição
guardrail_id → guardrail habilitadoaquele guardrail
guardrail_id → guardrail desabilitadonada (sem fallback)
guardrail_id → deletado / ausentenada (sem fallback)
guardrail_id = 0 / não definidopadrão do workspace, se houver
Desabilitar um guardrail vinculado é o botão de desligar para essa chave, não um downgrade para o padrão. Se você quer que uma chave caia para o padrão do workspace, limpe seu vínculo (defina guardrail_id como 0) — não apenas desabilite o guardrail para o qual ela aponta.
Esta é uma diferença deliberada em relação ao firewall: uma chave com uma política de firewall vinculada e desabilitada cai para a política de firewall padrão do workspace, enquanto um guardrail vinculado e desabilitado resolve para nenhum. Mesma ideia, fallback oposto — veja Guardrails vs. firewall.

​
5. Desvincule ou limpe o vínculo

Para parar de filtrar uma chave com um guardrail específico, você tem dois movimentos distintos com resultados diferentes:
  • Limpe o vínculo — defina o guardrail_id da chave como 0. A chave agora resolve para o padrão do workspace (se houver), ou para nenhum.
  • Desabilite o guardrail — desligue o enabled do guardrail. Toda chave vinculada explicitamente a ele agora resolve para nenhum (conforme §4), enquanto as chaves que dependiam dele como o padrão do workspace caem para sem enforcement.
Escolha limpar quando você quer a chave na linha de base do workspace; escolha desabilitar quando você quer pausar essa política em todo lugar onde ela é o vínculo nomeado.

​
6. O que uma requisição filtrada custa (e não custa)

Uma vez que um guardrail resolve, suas regras decidem a requisição. Os dois resultados que vale conhecer para uma chave vinculada:
  • Um block retorna HTTP 400 com o código de erro guardrail_blocked, nomeando o guardrail e a regra que disparou. Ele custa nenhuma cota — um block no estágio de input dispara antes da medição, um block no estágio de output reembolsa a cota pré-consumida — e é marcado como skip-retry.
  • Um mask reescreve a correspondência para uma tag tipada (ex.: [EMAIL]) e deixa a requisição passar sanitizada; o modelo upstream nunca vê o original.
Veja a página do erro guardrail_blocked para o formato exato da resposta, e Cobertura de streaming para como as regras de output se comportam em respostas com stream.

​
7. Para onde ir a seguir

Crie seu primeiro guardrail

Construa a política que você vinculará a uma chave.

Guardrail padrão de conta

Filtre todas as chaves do workspace de uma vez.

Referência de Guardrails

Tipos de regra, ações, estágios, PII, judge, grounding.

Chaves, políticas e workspaces

Como os vínculos têm escopo no gateway.