Passer au contenu principal
Chaque credential à longue durée de vie devrait être remplacée selon un calendrier, et immédiatement à tout indice d’exposition. La façon sûre de faire la rotation des clés API n’est jamais de muter une clé vivante sur place — c’est de frapper une nouvelle clé, de déplacer le trafic vers elle, et de retirer l’ancienne une fois que rien n’en dépend. Fait dans cet ordre, il n’y a jamais de moment sans clé fonctionnelle. Cette page est le playbook pas à pas. Pour le cycle de vie de clé plus large (créer / désactiver / supprimer) voir Gérer les clés ; pour chaque champ qu’une clé porte voir L’objet token.
Toutes les actions de console ici vivent dans l’écran Clés (/console/token) et s’exécutent sur votre session / token d’accès — pas la clé de relais. Créer, modifier, désactiver ou supprimer une clé requiert le rôle Developer ou supérieur. Seuls les appels d’inférence /v1/* utilisent la clé de relais sk-orca-….

​
1. Pourquoi faire la rotation, et pourquoi jamais sur place

Une clé sur OrcaRouter est une identité immuable, pas qu’une chaîne — elle porte sa propre allow-list de modèles, allow-list d’IP, plafond de dépense, expiration, et attachements de politique. Vous ne pouvez pas changer le matériel secret d’une clé existante ; la credential et les contraintes sont émises ensemble à la création. Donc « faire la rotation » signifie émettre un successeur et migrer vers lui. Faites-le :
  • à une cadence fixe pour toute credential de production (trimestriel est un référentiel commun) ;
  • dès qu’une clé est suspectée fuitée — bien que pour une fuite confirmée, il faille la couper d’abord et faire la rotation ensuite (voir Réponse à une clé fuitée) ;
  • chaque fois que le propriétaire de la clé (un employé, une intégration fournisseur, un agent décommissionné) change.
Le plaintext (sk-orca-…) est montré une fois, à la création — copiez-le alors. Ensuite la console ne montre qu’une forme masquée comme orca-7Bf****wxyz. Un Developer+ peut re-révéler le plaintext d’une clé ordinaire plus tard, mais une clé à portée de passerelle (is_firewall_gateway) requiert Admin pour relire son plaintext — alors traitez la première révélation de la clé de passerelle comme votre seule copie fiable.

​
2. La séquence de rotation de clé API

Tout l’intérêt est un chevauchement propre : la nouvelle clé fonctionne avant que l’ancienne s’arrête. Quatre étapes.
1

Créer la clé successeur

Frappez une nouvelle clé avec la même portée que celle que vous remplacez — les mêmes model_limits, allow_ips, credit_limit_usd, expired_time, et les mêmes guardrail_id / firewall_policy_id. Copiez le plaintext immédiatement. La rotation est le moment idéal pour resserrer la portée aussi : retirez un modèle que l’agent n’utilise plus, ou rétrécissez l’allow-list d’IP.
2

Migrer le trafic

Déployez la nouvelle sk-orca-… vers chaque appelant — config, gestionnaire de secrets, variable CI, runtime d’agent. Déployez-la de la même façon que vous livrez tout changement de secret. Les deux clés sont vivantes à ce point, donc les déploiements peuvent être échelonnés sans panne.
3

Vérifier que la nouvelle clé porte la charge

Confirmez que le successeur sert réellement du trafic avant de toucher l’ancienne. Regardez le used_quota de la nouvelle clé grimper tandis que celui de l’ancienne se stabilise — l’usage par clé est votre signal de bascule.
4

Retirer l'ancienne clé

Une fois que l’ancienne clé ne montre aucun trafic, désactivez-la d’abord (réversible) et surveillez les retardataires, puis supprimez-la pour de bon. Désactiver est la pause ; supprimer est le point de non-retour.
Définissez une étiquette environment sur chaque clé — réutilisez-la sur l’ancienne et la nouvelle clé, ou bumpez-la (prod → prod-2026q2) — pour que le successeur et le prédécesseur soient étiquetés distinctement pendant que les deux sont vivants durant la fenêtre de chevauchement.

​
3. Une rotation concrète, via REST

Tout ce qui suit est une action de console — ces routes de gestion s’exécutent sous votre session (UserAuth), pas la clé de relais. Supposons que vous remplaciez la clé d’un agent de résumé planifié. Créez le successeur avec la même portée : 
# Token de session de console — PAS une clé de relais sk-orca-…
curl https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer-2026q2",
    "environment": "prod",
    "model_limits_enabled": true,
    "model_limits": "openai/gpt-4o-mini",
    "credit_limit_usd": 50,
    "expired_time": -1,
    "guardrail_id": 12,
    "firewall_policy_id": 7
  }'
La réponse renvoie le plaintext une fois ("data": "sk-orca-…"). Copiez-le, déployez-le vers le résumeur, et confirmez que la nouvelle clé sert avant de continuer. Lorsque l’ancienne clé (id 481) ne montre aucun trafic, désactivez puis supprimez-la : 
# Mettez en pause d'abord (réversible) — passez le statut de l'ancienne clé à Disabled (2)
curl -X PUT https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 481, "status": 2}'

# Une fois certain que rien n'en dépend — révoquez pour de bon
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
Le statut d’une clé est l’un de Enabled (1), Disabled (2), Expired (3), ou Exhausted (4). Désactiver le passe à Disabled ; chaque requête que la clé effectue est alors rejetée tandis que sa config, ses attachements et son historique restent intacts. Supprimer est permanent — la credential ne peut plus jamais autoriser une requête, et une clé supprimée n’est pas récupérable.
Vous pouvez faire tout cela sans l’API — l’écran Clés a Nouvelle clé, un interrupteur Désactivé par clé, et Supprimer (unique ou en lot). La forme REST ci-dessus est pour scripter des rotations planifiées.

​
4. Faire la rotation des clés liées à une politique et des clés de passerelle

Les attachements de guardrail et firewall d’une clé vivent sur la clé, donc le successeur doit porter les mêmes guardrail_id et firewall_policy_id pour appliquer la même posture. Deux choses à savoir :
Les guardrails et politiques firewall sont des ressources nommées et à portée d’espace de travail, partagées entre les clés. Faire la rotation d’une clé ne touche pas la politique elle-même ; vous re-pointez juste une nouvelle clé vers les guardrail_id / firewall_policy_id existants. La politique continue de gouverner le trafic sans interruption.
Une clé avec is_firewall_gateway défini pilote les routes de la passerelle Firewall (/api/v1/firewall/*). Frapper une telle clé, et re-révéler son plaintext, requièrent tous deux Admin. Parce que vous ne pouvez pas relire facilement son secret, capturez le plaintext de la nouvelle clé de passerelle à la création et stockez-le dans votre gestionnaire de secrets avant de basculer.
Ne réutilisez pas une seule clé — passerelle ou autre — sur de nombreux agents et « faites la rotation » en modifiant les limites. Une clé par agent maintient chaque rotation isolée et le rayon d’explosion petit. Voir la Checklist de moindre agence.

​
5. Rotation d’urgence (fuite suspectée)

Si vous pensez qu’une clé est exposée, l’ordre s’inverse : arrêtez l’hémorragie d’abord, migrez ensuite.
  1. Désactivez la clé suspecte tout de suite pour qu’elle ne puisse rien autoriser pendant que vous enquêtez — ou supprimez-la carrément si la fuite est confirmée.
  2. Frappez le successeur et déployez-le comme en §2.
  3. Examinez ce que la clé fuitée a fait avant de la couper : filtrez les logs de requêtes par cette clé (token) pour scoper le rayon d’explosion.
Le runbook d’incident complet est sur Réponse à une clé fuitée.
Un expired_time court est une assurance de rotation : une clé expirante se retire d’elle-même même si vous oubliez la rotation manuelle, plafonnant combien de temps une seule credential peut jamais être abusée.

​
6. Étapes suivantes

Gérer les clés

Le cycle de vie créer / désactiver / révoquer sur lequel ces étapes s’appuient.

Lier des politiques à une clé

Porter le même guardrail et la même politique firewall sur le successeur.

Clés expirantes

Définir une expiration pour que les clés fassent leur rotation d’elles-mêmes à une échéance.

Réponse à une clé fuitée

Le chemin d’urgence quand une credential est exposée.
La rotation n’est qu’un chevauchement discipliné : un successeur qui fonctionne avant que le prédécesseur s’arrête. Gardez chaque clé à portée étroite et le transfert reste ennuyeux — ce qui est exactement ce que vous voulez d’une rotation de credential.