Passer au contenu principal
Une credential à longue durée de vie est une responsabilité qui grandit discrètement : l’agent est décommissionné, la démo se termine, le prestataire s’en va — mais la clé continue de fonctionner jusqu’à ce que quelqu’un se souvienne de la révoquer. Une clé API expirante inverse ce défaut. Vous fixez une date de fin lorsque vous frappez la clé, et OrcaRouter cesse de l’autoriser à l’instant où cette date passe — aucune tâche de nettoyage à oublier, aucune fenêtre fuitée-mais-encore-vivante. L’expiration est un champ de l’objet token : expired_time. Cette page est le guide ciblé de ce seul contrôle. Pour le volet plafond-de-dépense du même écran, voir Quota, plafond & expiration.

​
1. Pourquoi configurer une clé API expirante

L’intérêt d’une clé à durée limitée est de faire de l’issue sûre l’issue par défaut. Quelques cas où cela paie :

Agents éphémères

Un job planifié ou un agent à courte durée de vie reçoit une clé qui meurt avec le cycle de vie du déploiement. Une tâche cron oubliée ne peut pas continuer à dépenser des mois plus tard.

Démos & essais

Remettez à un prospect une clé qui fonctionne pour la durée de l’évaluation puis s’éteint d’elle-même — aucune révocation de suivi nécessaire.

Prestataires & fournisseurs

Scopez une credential à la fenêtre de la mission. Quand le contrat se termine, la clé aussi.

Accès scopé à un incident

Accordez une clé étroite et à courte durée de vie pendant un incident pour que l’accès élevé ne puisse pas survivre à l’incident lui-même.
L’expiration s’associe naturellement au reste d’une clé à moindre agence — une allow-list de modèles, une allow-list d’IP, et un plafond de dépense. Chacun borne un axe différent ; ensemble ils maintiennent petit le rayon d’explosion d’une clé compromise. Voir la Checklist de moindre agence.

​
2. Le champ expired_time

L’expiration d’une clé vit dans un seul champ de l’ objet token :
ChampTypeSignification
expired_timetimestamp Unix (secondes)L’instant absolu où la clé cesse d’autoriser. -1 signifie n’expire jamais.
Deux choses à garder à l’esprit :
  • expired_time est absolu, pas une durée. Vous fixez le moment où la clé meurt, pas « dans 30 jours » — le sélecteur de date de la console calcule le timestamp pour vous.
  • Le défaut pour une nouvelle clé est -1 (jamais). Une clé n’expire que si vous lui donnez un vrai timestamp ; laisser le champ intact frappe une clé non-expirante.
Une clé non-expirante (expired_time = -1) n’est le bon choix que pour une credential que vous faites activement tourner. Si vous pouvez nommer la date à laquelle une clé devrait cesser de fonctionner — et pour les agents, démos et prestataires vous le pouvez généralement — fixez-la. Une clé -1 non surveillée est celle la plus susceptible de survivre à son objectif.

​
3. Définir une expiration dans la console

Définir une expiration est une action de console sur votre session / token d’accès — pas quelque chose que vous passez sur un appel de relais. Créer ou modifier une clé requiert le rôle Developer ou supérieur.
  1. Ouvrez Clés (/console/token) et créez une nouvelle clé, ou modifiez-en une existante.
  2. Dans le champ expiration, choisissez la date et l’heure auxquelles la clé devrait cesser de fonctionner. Laissez-le vide (ou réglez sur jamais) pour garder la clé permanente.
  3. Enregistrez. Le changement prend effet immédiatement — aucun redéploiement, aucun changement de code d’agent.
Modifier l’expiration d’une clé existante est en direct : prolongez une clé sur le point d’expirer, ou avancez son expiration pour la retirer plus tôt, et la nouvelle échéance s’applique à la requête suivante.
Seuls les appels de relais /v1/* portent la clé sk-orca-…. L’expiration que vous définissez ici gouverne cette clé de relais, mais vous la configurez depuis la session de console, jamais en envoyant la clé de relais vers une route de gestion.

​
4. Ce que fait une clé expirée

Lorsqu’une clé est présentée après que son expired_time est passé, la passerelle la rejette à la couche d’authentification — la requête n’atteint jamais un modèle, donc elle ne coûte aucun quota. Le statut de la clé passe à Expired, l’un des états de fin automatiques qu’une clé peut atteindre :
StatutAtteint comment
EnabledActive ; les requêtes sont autorisées.
DisabledVous l’avez mise en pause ; réversible.
ExpiredAu-delà de son expired_time — atteint automatiquement.
ExhaustedAu-delà de son plafond de quota / dépense — atteint automatiquement.
Expired est terminal au sens où la clé ne s’autorisera plus d’elle-même. Si vous en avez besoin à nouveau, modifiez la clé pour pousser expired_time dans le futur (Developer+) et elle revient à Enabled à la requête suivante — la clé, ses limites et ses attachements de politique sont tous préservés. Pour retirer une clé pour de bon à la place, révoquez-la.
Expiration vs. désactivation vs. révocation. L’expiration est l’interrupteur d’arrêt programmé — vous décidez l’échéance en amont et vous vous en allez. Désactiver est la pause manuelle et réversible pour un incident. Révoquer (supprimer) est permanent. Optez pour l’expiration chaque fois que vous savez déjà quand une credential devrait cesser d’avoir de l’importance.

​
5. Un exemple travaillé : une clé de démo de deux semaines

Supposons que vous donnez à un prospect une clé pour une évaluation de 14 jours. Vous voulez qu’elle appelle un seul modèle bon marché, ne dépense pas plus qu’un budget fixe, et s’éteigne quand l’essai se termine — le tout sans rappel d’agenda pour la révoquer. Dans la boîte de dialogue Nouvelle clé, définissez :
  • model_limits : ["openai/gpt-4o-mini"] — la démo ne peut pas viser un modèle plus cher.
  • credit_limit_usd : un budget d’essai fixe — une boucle emballée ne peut pas le dépasser.
  • expired_time : la fin de la fenêtre de 14 jours — la clé cesse d’autoriser d’elle-même quand l’essai est terminé.
Après l’échéance, toute requête supplémentaire sur cette clé est rejetée sans quota dépensé, et la clé affiche Expired dans la liste. Rien à nettoyer pour vous ; la credential s’est retirée elle-même. 
# Avant l'expiration — autorisé
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":"ping"}]}'

# Après l'expiration — le même appel est rejeté à la couche d'authentification,
# le modèle n'est jamais invoqué, et aucun quota n'est consommé.

​
6. Qui peut faire quoi

L’expiration est gouvernée par la même barrière de rôle que le reste du cycle de vie d’une clé, scopée à votre espace de travail actif :
ActionRôle minimum
Voir l’expiration d’une cléViewer
Définir ou changer expired_time (créer / modifier une clé)Developer
Re-révéler le plaintext d’une clé ordinaireDeveloper
Lire le plaintext d’une clé à portée de passerelle (is_firewall_gateway)Admin
Pour le cycle de vie complet — créer, désactiver, révoquer — et le motif de rotation qui s’associe à l’expiration, voir Gérer les clés.

​
7. Étapes suivantes

Quota, plafond & expiration

Le pendant plafond-de-dépense de l’expiration — bornez une clé par les dollars autant que par le temps.

Rotation des clés

Le transfert sans interruption qui empêche une clé non-expirante de vivre éternellement.

L'objet token

Chaque champ qu’une clé porte, y compris expired_time, et ce que chacun contraint.

Checklist de moindre agence

Combinez l’expiration avec les limites de modèles, les allow-lists d’IP et les plafonds de dépense pour une clé à rayon d’explosion minimal.
Une clé qui sait quand s’arrêter est une credential de moins que vous avez à penser à retirer. Définissez expired_time chaque fois que vous pouvez nommer la date — et laissez la passerelle faire le nettoyage pour vous.