Saltar para o conteúdo principal
Você está construindo um SaaS onde muitos tenants-clientes compartilham uma base de código e um workspace OrcaRouter. Cada tenant envia prompts e roda agentes através do seu gateway, e o problema difícil é o raio de explosão: uma chave de tenant vazada, um agente de tenant descontrolado ou a PII de um tenant caindo nos logs de outro não pode transbordar a fronteira. Esta receita conecta os três controles que tornam um gateway compartilhado seguro para tenants — uma chave com escopo por tenant, política em nível de workspace que cada tenant herda e overrides por tenant onde um tenant precisa de mais — tudo a partir do console, com zero mudança no código da sua aplicação.
Tudo aqui se vincula ao seu workspace e é configurado a partir do console. Sua app continua chamando https://api.orcarouter.ai/v1/chat/completions com a chave sk-orca-... de cada tenant — apenas a política no gateway muda. As ações de configuração precisam dos papéis indicados por etapa; apenas as chamadas de relay /v1/* usam uma chave de tenant.

​
1. O modelo de segurança de IA multi-tenant

Um gateway multi-tenant tem um formato de ameaça diferente de uma app única. Os riscos que importam escalam com o número de tenants:

Vazamento de chave = raio de explosão de um tenant

Uma chave de tenant vazada não deveria conseguir drenar sua conta, chamar modelos que você nunca expôs, ou alcançar além do orçamento desse tenant.

Vazamento de dados cross-tenant

A PII de um tenant caindo em logs compartilhados, ou em uma resposta roteada para outro tenant, quebra sua promessa de isolamento de dados.

Um agente de tenant barulhento

O agente de um tenant em loop numa ferramenta ou buscando hosts arbitrários não deveria degradar o gateway para todos os outros.

Compliance por tenant

Um tenant regulado pode precisar de máscara de PII e residência de dados que o resto dos seus tenants não precisa.
O modelo abaixo são duas camadas: uma linha de base de workspace que cada chave de tenant herda, mais escopo e overrides por chave que restringem um tenant sem tocar nos outros. Veja escope chaves, políticas, workspaces para as regras de resolução completas.

​
2. A linha de base: uma política de workspace que cada tenant herda

Crie sua postura de segurança uma vez no nível de workspace para que cada chave de tenant a herde por padrão — sem duplicação por tenant.
1

Um guardrail padrão

Em Guardrails → New guardrail, crie uma política nomeada (ex.: tenant-baseline) e marque-a como padrão do workspace (is_default). Adicione uma regra de PII, stage input, ação mask, para que nenhuma requisição de tenant carregue PII bruta upstream:
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "credit_card", "ssn", "ip"],
  "entity_actions": { "credit_card": "block", "ssn": "block" }
}
Qualquer chave de tenant sem vínculo explícito de guardrail cai de volta para este padrão. Criar um guardrail precisa do papel Developer.
2

Uma política de firewall padrão

Se seus tenants rodam agentes, faça o mesmo no plano de ação: em Firewall → Policies, crie uma política padrão ou — mais rápido — abra Firewall → Posture e aplique o nível de autonomia balanced. Isso audita as chamadas de ferramenta de cada tenant e sinaliza PII em todo o workspace enquanto nega as ações mais destrutivas, então você observa o comportamento real do tenant antes de aplicar enforcement amplamente. Papel Developer.
Faça o rollout da linha de base na ordem observe → shadow → enforce para que uma regra nova não possa quebrar um tenant em voo. Uma política de firewall suporta uma flag shadow_mode por política (vereditos de enforcement registram como [shadow] would …); comece as regras de guardrail na ação flag. Veja modos de enforcement.

​
3. Uma chave com escopo por tenant

Este é o núcleo do isolamento de tenant: nunca compartilhe uma chave entre tenants, e nunca entregue a um tenant sua chave para toda a conta. Cunhe uma chave por tenant, escopada exatamente ao que aquele tenant pode fazer. Em API Keys → New key, defina:
Defina credit_limit_usd no teto daquele tenant (0 = ilimitado). Este é o controle multi-tenant mais importante: uma chave de tenant vazada ou abusada só pode queimar o orçamento daquele tenant, nunca sua conta. Veja denial-of-wallet.
Ative model_limits (model_limits_enabled) e liste apenas o(s) modelo(s) que o plano daquele tenant inclui — para que uma chave vazada não possa rodar um modelo caro que o tenant nunca pagou.
Defina environment (um rótulo de deploy de forma livre, ex.: prod / staging) para que o tráfego de um tenant seja atribuível nos seus logs e você possa distinguir chaves de produção das de teste num relance.
Defina allow_ips para os IPs de egress do backend daquele tenant se ele chama de um servidor fixo, e expired_time para tenants em trial ou limitados por tempo (-1 = nunca expira).
Cada chave de tenant herda o guardrail tenant-baseline do workspace e a política de firewall padrão automaticamente — você cunhou uma chave com escopo, e ela já está governada. A chave é mascarada na exibição após a criação, então copie-a uma vez quando provisionar o tenant.

​
4. Overrides por tenant — restrinja um sem tocar no resto

A maioria dos tenants anda na linha de base. Quando um precisa de mais — um tenant regulado, um tier enterprise, um tenant numa lista de probation — vincule uma política nomeada mais rígida somente àquela chave:
Defina na chaveEfeito para aquele único tenant
guardrail_idTroca por um guardrail nomeado mais rígido (ex.: block-on-PII).
firewall_policy_idTroca por uma política de firewall mais apertada (ex.: ferramentas default-deny).
A resolução difere entre os dois planos — conheça a diferença:
Um guardrail_id explícito (quando existe e está habilitado) sempre se aplica e nunca cai de volta silenciosamente. Se aquele guardrail vinculado está desabilitado, a chave fica com nenhum guardrail — ela não cai para o padrão do workspace. Deixe guardrail_id sem definir (0/null) para herdar o padrão tenant-baseline.
Um firewall_policy_id vinculado se aplica quando existe e está habilitado; se aquela política está desabilitada, a chave cai de volta para a política de firewall padrão do workspace. (Isto é o oposto do comportamento de interruptor de desligar do guardrail — por design.)
Editar uma política nomeada muda cada chave vinculada a ela na próxima chamada. Se múltiplos tenants compartilham uma política mais rígida, uma edição atinge todos eles de uma vez. Use uma política nomeada distinta por classe de isolamento, não uma política gigante compartilhada, quando os tenants precisam de regras genuinamente diferentes.

​
5. Um exemplo concreto de dois tiers

Digamos que você opera um tier gratuito e um tier enterprise regulado em um workspace:
  1. Linha de base do workspace — guardrail tenant-baseline (máscara de PII no input, block em cartão/SSN) como is_default, mais o nível de autonomia de firewall balanced. Cada tenant herda isto.
  2. Chave de tenant do tier gratuito — sem guardrail_id (herda a linha de base), model_limits fixado em openai/gpt-4o-mini, um credit_limit_usd baixo.
  3. Chave de tenant enterprise — guardrail_id definido para um guardrail enterprise-pii mais rígido (PII block, não mask, no input; block de secrets no stage output), um firewall_policy_id com uma allow-list de ferramentas mais apertada, um teto de crédito maior e allow_ips fixado ao backend deles.
Ambos os tiers chamam o mesmo endpoint /v1/chat/completions com sua própria chave. O gateway resolve a política certa por chave — o código da sua aplicação é idêntico para cada tenant.

​
6. Compliance e residência por tenant

Um tenant regulado frequentemente precisa de uma atestação que o resto não precisa. O compliance roda como um par de workspace dos guardrails e do firewall:
  • Navegar pelo catálogo de frameworks e prontidão está aberto a qualquer Member e é gratuito — confirme a cobertura para o framework sobre o qual um tenant pergunta (soc2, hipaa, gdpr, iso_27001, pci_dss e mais).
  • Instalar um pack (POST /api/compliance/packs/:key/install) materializa os guardrails e políticas de firewall correspondentes no seu workspace; exige Admin do workspace e um plano pago.
  • Residência de dados fixa a região do seu artefato de relatório de compliance (us / eu / uk / ap / cn / global) via PUT /api/compliance/residency (Admin). Leituras cross-region são retidas.
A residência aqui governa o artefato de relatório de compliance, não a geo-fixação de dados de inferência. Para a história dos request-log: os logs são retidos por um padrão de 30 dias (limitados rigidamente a 180), e uma autoexclusão de usuário roda uma carência de 30 dias depois uma limpeza de PII que cascateia para as guardrail matches e request logs desse usuário.
Para uma run de evidência totalmente auditada, veja gere evidência SOC 2 e faça deploy para HIPAA.

​
7. Observe cada tenant de um workspace

Toda a observabilidade tem escopo de workspace, então um conjunto de feeds cobre todos os seus tenants — filtrável até um único:
  • Guardrails → Matches (qualquer Member) — toda regra que disparou em todos os tenants: tipo, ação, stage, detalhe. A substring correspondente é registrada somente se Log raw content estiver ligado para aquele guardrail (desligado por padrão — a postura conservadora de privacidade, que mais importa em multi-tenant). Marque um falso positivo para ajustar (Admin).
  • Firewall → Events / Runs (Developer+) — cada chamada de ferramenta, consolidada por run de agente, para que o loop de um tenant barulhento ou um egress inédito se destaque.
  • Feed de anomalias (Member) — picos de taxa/custo pontuados contra uma baseline aprendida de hora-da-semana capturam um tenant queimando fora do padrão mesmo quando cada chamada é individualmente permitida.
Uma requisição bloqueada retorna HTTP 400 (guardrail_blocked / firewall_blocked), custa nenhuma cota daquele tenant e é marcada como skip-retry — a fronteira se sustentou sem cobrar o tenant pela rejeição.

​
8. Para onde aprofundar

Escope chaves, políticas, workspaces

A ordem de resolução completa para vínculo de chave e padrões de workspace.

Referência de Guardrails

Cada tipo de regra, entidade de PII e override por entidade por completo.

Referência de Firewall

Vereditos, superfícies, níveis de autonomia e o plano de política.

Pare a exfiltração de dados

Restrinja o egress outbound do agente de um tenant.