Passer au contenu principal
Vous avez un guardrail enregistré et vous voulez qu’une clé API spécifique soit filtrée par lui — pas tout l’espace de travail. C’est à ça que sert la liaison guardrail par clé API : définissez guardrail_id sur la clé et chaque appel /v1/* effectué avec cette clé est filtré dès la prochaine requête, sans redéploiement et sans changement de SDK. Cette page couvre uniquement la liaison — comment attacher, comment la résolution choisit la politique effective, et ce que fait l’interrupteur d’arrêt. Pour les types de règles, les actions et les étapes, voir la référence Guardrails.

​
1. Lier un guardrail par clé API avec guardrail_id

Un guardrail est à portée d’espace de travail, mais l’application est décidée par clé. Chaque clé API porte un champ guardrail_id. Pointez-le vers un guardrail et cette clé — et uniquement cette clé — est filtrée par cette politique. Cela permet à un espace de travail d’exécuter différentes politiques sur différentes clés :
  • une clé de production liée à un pii-blocker strict,
  • une clé de staging liée à une politique flag-only plus légère,
  • une clé interne sans rien d’attaché.
La liaison vit sur la clé dans la passerelle, donc modifier le guardrail déplace la clé liée dès sa prochaine requête. Votre application continue d’appeler https://api.orcarouter.ai/v1/chat/completions exactement comme avant.
La clé de relais (sk-orca-…) est ce que votre application envoie. Attacher un guardrail à celle-ci est une action de console / API token authentifiée par votre session — vous ne configurez jamais un guardrail avec la clé de relais elle-même.

​
2. L’attacher dans la console

Configurez la liaison depuis la console (soumise à des rôles : modifier les clés et les guardrails nécessite Developer+).
1

Ouvrir la clé

Allez sur /console/token et créez ou modifiez la clé API que vous voulez filtrer.
2

Choisir le guardrail

Dans l’éditeur de clé, choisissez votre guardrail dans la liste déroulante Guardrail. Cela définit guardrail_id sur la clé.
3

Enregistrer

La liaison prend effet à la prochaine requête de cette clé. Aucun redéploiement.
Après cela, un appel de relais normal avec la clé liée est filtré automatiquement : 
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 le guardrail lié masque l’email à l’étape input, le modèle en amont voit [EMAIL] et jamais l’adresse — même appel, aucun changement client.
Pour filtrer chaque clé de l’espace de travail au lieu d’une seule, définissez le guardrail comme défaut de l’espace de travail plutôt que de lier chaque clé. Voir Guardrail par défaut de compte.

​
3. Comment la résolution choisit le guardrail effectif

À chaque requête, la passerelle résout exactement un guardrail effectif (ou aucun) dans cet ordre :
Si le guardrail_id de la clé pointe vers un guardrail et que ce guardrail existe et est activé, il s’applique. Un attachement explicite fait autorité — il ne retombe jamais silencieusement sur le défaut de l’espace de travail.
Si la clé n’a aucun attachement (guardrail_id vaut 0 / non défini), le guardrail par défaut activé de l’espace de travail s’applique, s’il y en a un de défini.
Aucune application. La requête est identique octet pour octet à un espace de travail qui n’a jamais activé la fonctionnalité — rien de bloqué, masqué ou journalisé.
La décision est une seule recherche indexée sur le chemin à chaud et est fail-open : si la résolution rencontre une erreur transitoire, la passerelle dégrade vers aucune application plutôt que de faire échouer la requête. La sécurité se dégrade ; la disponibilité est préservée.

​
4. L’interrupteur d’arrêt : désactiver un attachement, aucun fallback

C’est la partie que les gens manquent. Un attachement explicite de clé est sa propre autorité — donc désactiver le guardrail attaché coupe l’application pour cette clé, et il ne retombe pas sur le défaut de l’espace de travail.
État de la cléCe qui filtre la requête
guardrail_id → guardrail activéce guardrail
guardrail_id → guardrail désactivérien (aucun fallback)
guardrail_id → supprimé / manquantrien (aucun fallback)
guardrail_id = 0 / non définidéfaut de l’espace de travail, s’il y en a un
Désactiver un guardrail attaché est l’interrupteur d’arrêt pour cette clé, pas une rétrogradation vers le défaut. Si vous voulez qu’une clé retombe sur le défaut de l’espace de travail, effacez son attachement (mettez guardrail_id à 0) — ne désactivez pas simplement le guardrail vers lequel elle pointe.
C’est une différence délibérée avec le firewall : une clé avec une politique firewall attachée désactivée retombe bien sur la politique firewall par défaut de l’espace de travail, tandis qu’un guardrail attaché désactivé se résout vers rien. Même idée, fallback opposé — voir Guardrails vs. firewall.

​
5. Détacher ou effacer la liaison

Pour arrêter de filtrer une clé avec un guardrail spécifique, vous avez deux mouvements distincts aux résultats différents :
  • Effacer l’attachement — mettez le guardrail_id de la clé à 0. La clé se résout désormais vers le défaut de l’espace de travail (s’il en existe un), ou vers rien.
  • Désactiver le guardrail — basculez le enabled du guardrail sur off. Chaque clé explicitement attachée à lui se résout désormais vers rien (selon §4), tandis que les clés qui s’appuyaient sur lui en tant que défaut de l’espace de travail basculent vers aucune application.
Choisissez effacer quand vous voulez la clé sur le référentiel de l’espace de travail ; choisissez désactiver quand vous voulez mettre en pause cette politique partout où elle est l’attachement nommé.

​
6. Ce qu’une requête filtrée coûte (et ne coûte pas)

Une fois qu’un guardrail se résout, ses règles décident de la requête. Les deux résultats à connaître pour une clé liée :
  • Un block renvoie une HTTP 400 avec le code d’erreur guardrail_blocked, nommant le guardrail et la règle qui s’est déclenchée. Il ne coûte aucun quota — un block à l’étape input se déclenche avant la mesure, un block à l’étape output rembourse le quota pré-consommé — et il est marqué skip-retry.
  • Un mask réécrit la correspondance en une balise typée (par exemple [EMAIL]) et laisse passer la requête assainie ; le modèle en amont ne voit jamais l’original.
Voir la page erreur guardrail_blocked pour la forme exacte de la réponse, et Couverture du streaming pour le comportement des règles de sortie sur les réponses streamées.

​
7. Où aller ensuite

Créer votre premier guardrail

Construisez la politique que vous lierez à une clé.

Guardrail par défaut de compte

Filtrez chaque clé de l’espace de travail d’un coup.

Référence Guardrails

Types de règles, actions, étapes, PII, juge, ancrage.

Clés, politiques & espaces de travail

Comment les liaisons sont scopées à travers la passerelle.