Saltar al contenido principal
Tienes un guardrail guardado y quieres que una clave API específica sea examinada por él — no todo el espacio de trabajo. Para eso sirve la vinculación de guardrail por clave API: establece guardrail_id en la clave y cada llamada /v1/* hecha con esa clave se examina en la siguiente solicitud, sin redespliegue y sin cambio de SDK. Esta página cubre solo la vinculación — cómo vincular, cómo la resolución elige la política efectiva y qué hace el interruptor de apagado. Para los tipos de regla, acciones y etapas, ver la referencia de Guardrails.

​
1. Vincula un guardrail por clave API con guardrail_id

Un guardrail tiene alcance de espacio de trabajo, pero la aplicación se decide por clave. Cada clave API lleva un campo guardrail_id. Apúntalo a un guardrail y esa clave — y solo esa clave — es examinada por esa política. Esto permite que un espacio de trabajo ejecute diferentes políticas en diferentes claves:
  • una clave de producción vinculada a un pii-blocker estricto,
  • una clave de staging vinculada a una política flag-only más ligera,
  • una clave interna sin nada vinculado.
La vinculación vive en la clave dentro del gateway, así que editar el guardrail surte efecto en la clave vinculada en su siguiente solicitud. Tu aplicación sigue llamando a https://api.orcarouter.ai/v1/chat/completions exactamente como antes.
La clave de relay (sk-orca-…) es lo que tu app envía. Vincular un guardrail a ella es una acción de consola / API de tokens autenticada por tu sesión — nunca configuras un guardrail con la propia clave de relay.

​
2. Vincúlalo en la consola

Configura la vinculación desde la consola (restringido por rol: editar claves y guardrails requiere Developer+).
1

Abre la clave

Ve a /console/token y crea o edita la clave API que quieres examinar.
2

Elige el guardrail

En el editor de claves, elige tu guardrail del desplegable Guardrail. Esto establece guardrail_id en la clave.
3

Guarda

La vinculación surte efecto en la siguiente solicitud de esa clave. Sin redespliegue.
Después de eso, una llamada de relay normal con la clave vinculada se examina automáticamente: 
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"}
    ]
  }'
Si el guardrail vinculado enmascara email en la etapa de entrada, el modelo upstream ve [EMAIL] y nunca la dirección — misma llamada, sin cambio en el cliente.
Para examinar cada clave del espacio de trabajo en vez de una, establece el guardrail como el valor por defecto del espacio de trabajo en vez de vincular cada clave. Ver Guardrail por defecto de cuenta.

​
3. Cómo la resolución elige el guardrail efectivo

En cada solicitud, el gateway resuelve exactamente un guardrail efectivo (o ninguno) en este orden:
Si el guardrail_id de la clave apunta a un guardrail y ese guardrail existe y está habilitado, aplica. Una vinculación explícita es autoritativa — nunca hace fallback silencioso al valor por defecto del espacio de trabajo.
Si la clave no tiene vinculación (guardrail_id es 0 / sin establecer), aplica el guardrail por defecto habilitado del espacio de trabajo, si hay uno establecido.
Sin aplicación. La solicitud es idéntica byte a byte a un espacio de trabajo que nunca habilitó la función — nada bloqueado, enmascarado o registrado.
La decisión es una sola búsqueda indexada en la ruta caliente y es fail-open: si la resolución encuentra un error transitorio, el gateway degrada a sin aplicación en vez de fallar la solicitud. La seguridad se degrada; la disponibilidad se preserva.

​
4. El interruptor de apagado: deshabilita una vinculación, sin fallback

Esta es la parte que la gente pasa por alto. Una vinculación explícita de clave es su propia autoridad — así que deshabilitar el guardrail vinculado APAGA la aplicación para esa clave, y no hace fallback al valor por defecto del espacio de trabajo.
Estado de la claveQué examina la solicitud
guardrail_id → guardrail habilitadoese guardrail
guardrail_id → guardrail deshabilitadonada (sin fallback)
guardrail_id → eliminado / inexistentenada (sin fallback)
guardrail_id = 0 / sin establecervalor por defecto del espacio de trabajo, si hay
Deshabilitar un guardrail vinculado es el interruptor de apagado para esa clave, no una degradación al valor por defecto. Si quieres que una clave haga fallback al valor por defecto del espacio de trabajo, limpia su vinculación (establece guardrail_id en 0) — no solo deshabilites el guardrail al que apunta.
Esta es una diferencia deliberada respecto al firewall: una clave con una política de firewall vinculada deshabilitada sí hace fallback a la política de firewall por defecto del espacio de trabajo, mientras que un guardrail vinculado deshabilitado resuelve a ninguno. Misma idea, fallback opuesto — ver Guardrails vs. firewall.

​
5. Desvincula o limpia la vinculación

Para dejar de examinar una clave con un guardrail específico, tienes dos movimientos distintos con resultados diferentes:
  • Limpia la vinculación — establece el guardrail_id de la clave en 0. La clave ahora resuelve al valor por defecto del espacio de trabajo (si existe), o a ninguno.
  • Deshabilita el guardrail — apaga el enabled del guardrail. Cada clave vinculada explícitamente a él ahora resuelve a ninguno (según §4), mientras que las claves que dependían de él como valor por defecto del espacio de trabajo caen a sin aplicación.
Elige limpiar cuando quieres la clave en la línea base del espacio de trabajo; elige deshabilitar cuando quieres pausar esa política en todas partes donde sea la vinculación nombrada.

​
6. Qué cuesta (y qué no) una solicitud examinada

Una vez que un guardrail resuelve, sus reglas deciden la solicitud. Los dos resultados que vale la pena conocer para una clave vinculada:
  • Un block devuelve HTTP 400 con el código de error guardrail_blocked, nombrando el guardrail y la regla que se disparó. No cuesta cuota — un bloqueo en la etapa de entrada se dispara antes de la medición, un bloqueo en la etapa de salida reembolsa la cuota preconsumida — y se marca como skip-retry.
  • Un mask reescribe la coincidencia a una etiqueta tipada (p. ej. [EMAIL]) y deja pasar la solicitud saneada; el modelo upstream nunca ve el original.
Ver la página del error guardrail_blocked para la forma exacta de la respuesta, y Cobertura de streaming para cómo se comportan las reglas de salida en respuestas con streaming.

​
7. Dónde ir a continuación

Crea tu primer guardrail

Construye la política que vincularás a una clave.

Guardrail por defecto de cuenta

Examina cada clave del espacio de trabajo de una vez.

Referencia de Guardrails

Tipos de regla, acciones, etapas, PII, judge, grounding.

Claves, políticas y espacios de trabajo

Cómo se delimitan las vinculaciones a través del gateway.