Rotation du secret d'agent

Renouvelez le client_secret d'un agent IA en un appel, donnez-lui une expiration pour que les identifiants périmés meurent d'eux-mêmes, et scriptez la rotation pour une vraie hygiène des secrets.

Les agents confidentiels s'authentifient au token endpoint avec un client_secret. Les secrets fuient : ils finissent dans des logs, des variables de CI, des dépôts forkés, et l'agent qui les détient survit souvent à la personne qui les a créés. Obexal traite la rotation comme une opération de premier rang et vous laisse donner à chaque secret une date d'expiration, appliquée en mode fail-closed.

Renouveler un secret

POST /v1/admin/agents/{clientId}/secret génère un nouveau secret, avec une durée de vie optionnelle dans le corps. L'appel exige la permission apps:manage, avec un jeton d'API d'administration (Authorization: Bearer obx_...) ou une session de console. Dans la console, c'est une action sensible : une vérification MFA fraîche est exigée. Si votre organisation utilise un domaine personnalisé, il remplace accounts.obexal.com.

curl -sS -X POST https://accounts.obexal.com/v1/admin/agents/$AGENT_ID/secret \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds": 7776000}'

{
  "secret": "kJ2mX0aQ3vTzq8Rw5nY7cD1fH4bL6sN9pE0uG2iA5oM",
  "secretExpiresAt": "2026-09-30T09:14:03Z"
}

Trois choses à savoir :

• Le secret n'est montré qu'une seule fois. Seul son SHA-256 est stocké : personne, Obexal compris, ne peut l'afficher à nouveau. Placez-le immédiatement dans votre gestionnaire de secrets.
• L'ancien secret cesse immédiatement de fonctionner. Il n'y a pas de fenêtre de recouvrement avec deux secrets valides : mettez à jour le déploiement de l'agent juste après la rotation.
• Seuls les clients confidentiels ont un secret. Renouveler un agent public (PKCE, sans secret) répond 400. ttlSeconds: 0 ou omis signifie un secret sans expiration.

L'expiration est appliquée en fail-closed

Quand secretExpiresAt est dépassé, l'authentification au token endpoint est refusée avec invalid_client, même si la valeur du secret présenté est correcte. Un secret expiré ne peut pas être discrètement maintenu en service : la seule issue est une rotation. Chaque tentative refusée lève aussi une anomalie expired_secret, voir Kill switch et détection d'anomalies.

L'inventaire des agents (GET /v1/admin/agents et la console) expose secretExpiresAt et secretExpired pour chaque agent confidentiel ; un secret périmé s'affiche avec un badge rouge « secret expiré », impossible à manquer.

Choisir une durée de vie

La console propose les mêmes valeurs que vous pouvez passer dans ttlSeconds :

Un bon défaut est 90 jours. Choisissez 30 jours pour les agents aux scopes larges ou aux audiences sensibles, et réservez « sans expiration » aux cas où vous tournez déjà les secrets selon un calendrier externe strict.

Scripter la rotation

La bonne pratique est une rotation régulière et scriptée via l'API, par exemple depuis une tâche planifiée :

#!/bin/sh
# Renouvelle le secret de l'agent (nouvelle durée de vie de 90 jours) et le stocke.
RESP=$(curl -sS -X POST "https://accounts.obexal.com/v1/admin/agents/$AGENT_ID/secret" \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds": 7776000}')
printf '%s' "$RESP" | jq -r '.secret' | secret-store put "agents/$AGENT_ID/client_secret"
# Puis redéployez ou rechargez l'agent pour qu'il prenne le nouveau secret.

L'expiration transforme ce calendrier en homme mort : si la tâche de rotation casse silencieusement, l'ancien secret meurt à sa date d'expiration au lieu de vivre pour toujours.

Trace d'audit

Chaque rotation est écrite au journal d'audit sous admin.agent.secret_rotated, avec pour cible agent:<clientId> et le nouveau secretExpiresAt en métadonnée quand une expiration a été fixée. Combiné à l'anomalie expired_secret, vous pouvez prouver à la fois que les rotations ont lieu et que les identifiants périmés sont réellement refusés.