1. Les trois portées
Trois concepts s’emboîtent les uns dans les autres :- Espace de travail — la frontière du tenant. Chaque membre d’un espace de travail partage le même catalogue de guardrails et de politiques firewall. Rien ne franchit les frontières d’espace de travail — une politique rédigée dans l’espace de travail A est invisible pour l’espace de travail B.
- Politique — un ensemble de règles nommé, à portée d’espace de travail (guardrail ou politique firewall). Modifier une politique prend effet sur chaque clé qui y est attachée à la prochaine requête, sans redéploiement.
- Clé — identité plus attachements. Une clé porte ses propres contraintes et pointe vers les politiques qui la gouvernent.
2. Ce qu’une clé transporte
Chaque clé API est un ensemble de limites et d’attachements. Définissez-les dans l’éditeur de clé (/console/token) — la création ou la modification de
clés nécessite le rôle Developer ou supérieur.
| Champ | Ce qu’il limite | Rôle minimum pour définir |
|---|---|---|
model_limits | Restreint la clé à une liste spécifique de modèles — tout appel en dehors de cette liste est rejeté avant de quitter la passerelle. | Developer |
allow_ips | Liste blanche d’IP. Les requêtes depuis toute adresse non répertoriée sont rejetées à la couche d’authentification. Vide signifie que toutes les IPs sont autorisées. | Developer |
credit_limit_usd | Plafond de dépenses en USD. 0 signifie illimité. La passerelle l’applique contre les dépenses à vie de la clé. | Developer |
expired_time | Horodatage d’expiration absolu. -1 signifie que la clé n’expire jamais. | Developer |
environment | Une étiquette libre (ex. prod, staging, dev) pour organiser les clés et filtrer les journaux. | Developer |
guardrail_id | Attache un guardrail spécifique à cette clé. Chaque appel que cette clé effectue est filtré par ce guardrail. | Developer |
firewall_policy_id | Attache une politique firewall spécifique à cette clé. Chaque appel d’outil que cette clé émet est évalué par cette politique. | Developer |
is_firewall_gateway | Marque la clé comme token scopé à la passerelle — requis pour appeler les routes de dispatch MCP et de hook d’évaluation. Une clé ordinaire obtient 403 sur ces routes. La lecture du texte en clair d’une clé de passerelle nécessite Admin. | Admin (pour activer et lire le texte en clair) |
3. Ordre de résolution des politiques
Pour toute requête, OrcaRouter résout le guardrail actif et la politique firewall indépendamment :- Attachement de clé — si la clé a un
guardrail_idexplicite (oufirewall_policy_id) et que cette politique existe et est activée, elle s’applique. - Défaut de l’espace de travail — si la clé n’a pas d’attachement, le
guardrail (ou la politique)
is_defaultactivé de l’espace de travail s’applique. - Aucune application — si aucun des deux n’est défini, la requête passe sans filtrage de contenu ni application des appels d’outils.
Les deux plans diffèrent quand une politique attachée est désactivée :
- Un attachement de guardrail désactivé ou supprimé signifie que la clé n’a aucun guardrail — le désactiver est l’interrupteur d’arrêt ; il ne revient pas sur le défaut de l’espace de travail.
- Un attachement de firewall désactivé revient à la politique firewall par défaut de l’espace de travail — donc désactiver un attachement firewall ramène la clé au défaut de l’espace de travail, ça ne désactive pas l’application.
0/non défini) revient toujours sur le défaut de
l’espace de travail ; ni l’un ni l’autre défini signifie aucune application.4. Clés à moindre agence — une clé par agent
La configuration la plus sûre est de donner à chaque agent sa propre clé étroitement scopée plutôt que de partager une seule clé d’espace de travail entre tous les appelants. Une clé bien scopée pour un agent qui n’appelle qu’un seul modèle et exécute des tâches planifiées pourrait ressembler à :model_limits:["openai/gpt-4o-mini"]— l’agent ne peut pas passer à un modèle plus cher ou plus capable.allow_ips: le CIDR d’egress du planificateur — aucune autre source ne peut présenter cette clé.credit_limit_usd: un plafond budgétaire hebdomadaire — une boucle incontrôlée ne peut pas épuiser le solde de votre espace de travail.expired_time: la fin du sprint ou du cycle de déploiement — la clé expire automatiquement et ne peut pas être réutilisée.guardrail_id: un guardrail spécifique à la sensibilité des données de cet agent — plus strict que le défaut de l’espace de travail.firewall_policy_id: une politique qui autorise uniquement les outils dont cet agent a légitimement besoin.
Créez des clés scopées passerelle (
is_firewall_gateway) uniquement pour la
surface de dispatch MCP ou de hook d’évaluation — jamais pour le trafic
d’inférence général. Une clé de passerelle sur le chemin d’inférence donne à
l’appelant accès aux routes /api/v1/firewall/*, ce qui est une capacité
plus large que nécessaire. Une clé, un but.5. Où les politiques sont rédigées
Les Guardrails et les politiques firewall sont tous deux à portée d’espace de travail et partagés entre tous les membres, mais les changements nécessitent le bon rôle :- Lire tout guardrail, politique ou clé — tout membre de l’espace de travail.
- Créer ou modifier des guardrails, des politiques firewall, des serveurs MCP, des niveaux d’autonomie, des actions d’approbation et des clés API ordinaires — Developer+.
- Activer
is_firewall_gatewaysur une clé ; lire le texte en clair d’une clé de passerelle — Admin+.
6. Prochaines étapes
Référentiel Secure Agents
La posture de départ recommandée — un interrupteur de niveau d’autonomie,
puis ajustez à partir du trafic réel.
Obtenir une clé API
Créez votre première clé et attachez un guardrail ou une politique
firewall dans la console.